tksbrokerapi.TKSBrokerAPI

   1# -*- coding: utf-8 -*-
   2# Author: Timur Gilmullin
   3
   4"""
   5**TKSBrokerAPI** is the trading platform for automation and simplifying the implementation of trading scenarios,
   6as well as working with Tinkoff Invest API server via the REST protocol. The TKSBrokerAPI platform may be used in two ways:
   7from the console, it has a rich keys and commands, or you can use it as Python module with `python import`.
   8
   9TKSBrokerAPI allows you to automate routine trading operations and implement your trading scenarios, or just receive
  10the necessary information from the broker. It is easy enough to integrate into various CI/CD automation systems.
  11
  12- **Open account for trading:** http://tinkoff.ru/sl/AaX1Et1omnH
  13- **TKSBrokerAPI module documentation:** https://tim55667757.github.io/TKSBrokerAPI/docs/tksbrokerapi/TKSBrokerAPI.html
  14- **See CLI examples:** https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md#Usage-examples
  15- **Used constants are in the TKSEnums module:** https://tim55667757.github.io/TKSBrokerAPI/docs/tksbrokerapi/TKSEnums.html
  16- **About Tinkoff Invest API:** https://tinkoff.github.io/investAPI/
  17- **Tinkoff Invest API documentation:** https://tinkoff.github.io/investAPI/swagger-ui/
  18"""
  19
  20# Copyright (c) 2022 Gilmillin Timur Mansurovich
  21#
  22# Licensed under the Apache License, Version 2.0 (the "License");
  23# you may not use this file except in compliance with the License.
  24# You may obtain a copy of the License at
  25#
  26#     http://www.apache.org/licenses/LICENSE-2.0
  27#
  28# Unless required by applicable law or agreed to in writing, software
  29# distributed under the License is distributed on an "AS IS" BASIS,
  30# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  31# See the License for the specific language governing permissions and
  32# limitations under the License.
  33
  34
  35import sys
  36import os
  37from argparse import ArgumentParser
  38from importlib.metadata import version
  39
  40from dateutil.tz import tzlocal
  41from time import sleep
  42
  43import re
  44import json
  45import requests
  46import traceback as tb
  47from typing import Union
  48
  49from multiprocessing import cpu_count, Lock
  50from multiprocessing.pool import ThreadPool
  51import pandas as pd
  52
  53from mako.template import Template  # Mako Templates for Python (https://www.makotemplates.org/). Mako is a template library provides simple syntax and maximum performance.
  54from Templates import *  # Some html-templates used by reporting methods in TKSBrokerAPI module
  55from TKSEnums import *  # A lot of constants from enums sections: https://tinkoff.github.io/investAPI/swagger-ui/
  56from TradeRoutines import *  # This library contains some methods used by trade scenarios implemented with TKSBrokerAPI module
  57
  58from pricegenerator.PriceGenerator import PriceGenerator, uLogger  # This module has a lot of instruments to work with candles data (https://github.com/Tim55667757/PriceGenerator)
  59from pricegenerator.UniLogger import DisableLogger as PGDisLog  # Method for disable log from PriceGenerator
  60
  61import UniLogger as uLog  # Logger for TKSBrokerAPI
  62
  63
  64# --- Common technical parameters:
  65
  66PGDisLog(uLogger.handlers[0])  # Disable 3-rd party logging from PriceGenerator
  67uLogger = uLog.UniLogger  # init logger for TKSBrokerAPI
  68uLogger.level = 10  # debug level by default for TKSBrokerAPI module
  69uLogger.handlers[0].level = 20  # info level by default for STDOUT of TKSBrokerAPI module
  70
  71__version__ = "1.6"  # The "major.minor" version setup here, but build number define at the build-server only
  72
  73CPU_COUNT = cpu_count()  # host's real CPU count
  74CPU_USAGES = CPU_COUNT - 1 if CPU_COUNT > 1 else 1  # how many CPUs will be used for parallel calculations
  75
  76
  77class TinkoffBrokerServer:
  78    """
  79    This class implements methods to work with Tinkoff broker server.
  80
  81    Examples to work with API: https://tinkoff.github.io/investAPI/swagger-ui/
  82
  83    About `token`: https://tinkoff.github.io/investAPI/token/
  84    """
  85    def __init__(self, token: str, accountId: str = None, useCache: bool = True, defaultCache: str = "dump.json") -> None:
  86        """
  87        Main class init.
  88
  89        :param token: Bearer token for Tinkoff Invest API. It can be set from environment variable `TKS_API_TOKEN`.
  90        :param accountId: string with numeric user account ID in Tinkoff Broker. It can be found in broker's reports.
  91                          Also, this variable can be set from environment variable `TKS_ACCOUNT_ID`.
  92        :param useCache: use default cache file with raw data to use instead of `iList`.
  93                         True by default. Cache is auto-update if new day has come.
  94                         If you don't want to use cache and always updates raw data then set `useCache=False`.
  95        :param defaultCache: path to default cache file. `dump.json` by default.
  96        """
  97        if token is None or not token:
  98            try:
  99                self.token = r"{}".format(os.environ["TKS_API_TOKEN"])
 100                uLogger.debug("Bearer token for Tinkoff OpenAPI set up from environment variable `TKS_API_TOKEN`. See https://tinkoff.github.io/investAPI/token/")
 101
 102            except KeyError:
 103                uLogger.error("`--token` key or environment variable `TKS_API_TOKEN` is required! See https://tinkoff.github.io/investAPI/token/")
 104                raise Exception("Token required")
 105
 106        else:
 107            self.token = token  # highly priority than environment variable 'TKS_API_TOKEN'
 108            uLogger.debug("Bearer token for Tinkoff OpenAPI set up from class variable `token`")
 109
 110        if accountId is None or not accountId:
 111            try:
 112                self.accountId = r"{}".format(os.environ["TKS_ACCOUNT_ID"])
 113                uLogger.debug("Main account ID [{}] set up from environment variable `TKS_ACCOUNT_ID`".format(self.accountId))
 114
 115            except KeyError:
 116                uLogger.warning("`--account-id` key or environment variable `TKS_ACCOUNT_ID` undefined! Some of operations may be unavailable (overview, trading etc).")
 117
 118        else:
 119            self.accountId = accountId  # highly priority than environment variable 'TKS_ACCOUNT_ID'
 120            uLogger.debug("Main account ID [{}] set up from class variable `accountId`".format(self.accountId))
 121
 122        self.version = __version__  # duplicate here used TKSBrokerAPI main version
 123        """Current TKSBrokerAPI version: major.minor, but the build number define at the build-server only.
 124
 125        Latest version: https://pypi.org/project/tksbrokerapi/
 126        """
 127
 128        self.__lock = Lock()  # initialize multiprocessing mutex lock
 129
 130        self.aliases = TKS_TICKER_ALIASES
 131        """Some aliases instead official tickers.
 132
 133        See also: `TKSEnums.TKS_TICKER_ALIASES`
 134        """
 135
 136        self.aliasesKeys = self.aliases.keys()  # re-calc only first time at class init
 137
 138        self.exclude = TKS_TICKERS_OR_FIGI_EXCLUDED  # some tickers or FIGIs raised exception earlier when it sends to server, that is why we exclude there
 139
 140        self._ticker = ""
 141        """String with ticker, e.g. `GOOGL`. Tickers may be upper case only.
 142
 143        Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR` etc.
 144        More tickers aliases here: `TKSEnums.TKS_TICKER_ALIASES`.
 145
 146        See also: `SearchByTicker()`, `SearchInstruments()`.
 147        """
 148
 149        self._figi = ""
 150        """String with FIGI, e.g. ticker `GOOGL` has FIGI `BBG009S39JX6`. FIGIs may be upper case only.
 151
 152        See also: `SearchByFIGI()`, `SearchInstruments()`.
 153        """
 154
 155        self.depth = 1
 156        """Depth of Market (DOM) can be >= 1. Default: 1. It used with `--price` key to showing DOM with current prices for givens ticker or FIGI.
 157
 158        See also: `GetCurrentPrices()`.
 159        """
 160
 161        self.server = r"https://invest-public-api.tinkoff.ru/rest"
 162        """Tinkoff REST API server for real trade operations. Default: https://invest-public-api.tinkoff.ru/rest
 163
 164        See also: API method https://tinkoff.github.io/investAPI/#tinkoff-invest-api_1 and `SendAPIRequest()`.
 165        """
 166
 167        uLogger.debug("Broker API server: {}".format(self.server))
 168
 169        self.timeout = 15
 170        """Server operations timeout in seconds. Default: `15`.
 171
 172        See also: `SendAPIRequest()`.
 173        """
 174
 175        self.headers = {
 176            "Content-Type": "application/json",
 177            "accept": "application/json",
 178            "Authorization": "Bearer {}".format(self.token),
 179            "x-app-name": "Tim55667757.TKSBrokerAPI",
 180        }
 181        """Headers which send in every request to broker server. Please, do not change it! Default: `{"Content-Type": "application/json", "accept": "application/json", "Authorization": "Bearer {your_token}"}`.
 182
 183        See also: `SendAPIRequest()`.
 184        """
 185
 186        self.body = None
 187        """Request body which send to broker server. Default: `None`.
 188
 189        See also: `SendAPIRequest()`.
 190        """
 191
 192        self.moreDebug = False
 193        """Enables more debug information in this class, such as net request and response headers in all methods. `False` by default."""
 194
 195        self.useHTMLReports = False
 196        """
 197        If `True` then TKSBrokerAPI generate also HTML reports from Markdown. `False` by default.
 198        
 199        See also: Mako Templates for Python (https://www.makotemplates.org/). Mako is a template library provides simple syntax and maximum performance.
 200        """
 201
 202        self.historyFile = None
 203        """Full path to the output file where history candles will be saved or updated. Default: `None`, it mean that returns only Pandas DataFrame.
 204
 205        See also: `History()`.
 206        """
 207
 208        self.htmlHistoryFile = "index.html"
 209        """Full path to the html file where rendered candles chart stored. Default: `index.html`.
 210
 211        See also: `ShowHistoryChart()`.
 212        """
 213
 214        self.instrumentsFile = "instruments.md"
 215        """Filename where full available to user instruments list will be saved. Default: `instruments.md`.
 216
 217        See also: `ShowInstrumentsInfo()`.
 218        """
 219
 220        self.searchResultsFile = "search-results.md"
 221        """Filename with all found instruments searched by part of its ticker, FIGI or name. Default: `search-results.md`.
 222
 223        See also: `SearchInstruments()`.
 224        """
 225
 226        self.pricesFile = "prices.md"
 227        """Filename where prices of selected instruments will be saved. Default: `prices.md`.
 228
 229        See also: `GetListOfPrices()`.
 230        """
 231
 232        self.infoFile = "info.md"
 233        """Filename where prices of selected instruments will be saved. Default: `prices.md`.
 234
 235        See also: `ShowInstrumentsInfo()`, `RequestBondCoupons()` and `RequestTradingStatus()`.
 236        """
 237
 238        self.bondsXLSXFile = "ext-bonds.xlsx"
 239        """Filename where wider Pandas DataFrame with more information about bonds: main info, current prices, 
 240        bonds payment calendar, some statistics will be stored. Default: `ext-bonds.xlsx`.
 241
 242        See also: `ExtendBondsData()`.
 243        """
 244
 245        self.calendarFile = "calendar.md"
 246        """Filename where bonds payment calendar will be saved. Default: `calendar.md`.
 247        
 248        Pandas dataframe with only bonds payment calendar also will be stored to default file `calendar.xlsx`.
 249
 250        See also: `CreateBondsCalendar()`, `ShowBondsCalendar()`, `ShowInstrumentInfo()`, `RequestBondCoupons()` and `ExtendBondsData()`.
 251        """
 252
 253        self.overviewFile = "overview.md"
 254        """Filename where current portfolio, open trades and orders will be saved. Default: `overview.md`.
 255
 256        See also: `Overview()`, `RequestPortfolio()`, `RequestPositions()`, `RequestPendingOrders()` and `RequestStopOrders()`.
 257        """
 258
 259        self.overviewDigestFile = "overview-digest.md"
 260        """Filename where short digest of the portfolio status will be saved. Default: `overview-digest.md`.
 261
 262        See also: `Overview()` with parameter `details="digest"`.
 263        """
 264
 265        self.overviewPositionsFile = "overview-positions.md"
 266        """Filename where only open positions, without everything else will be saved. Default: `overview-positions.md`.
 267
 268        See also: `Overview()` with parameter `details="positions"`.
 269        """
 270
 271        self.overviewOrdersFile = "overview-orders.md"
 272        """Filename where open limits and stop orders will be saved. Default: `overview-orders.md`.
 273
 274        See also: `Overview()` with parameter `details="orders"`.
 275        """
 276
 277        self.overviewAnalyticsFile = "overview-analytics.md"
 278        """Filename where only the analytics section and the distribution of the portfolio by various categories will be saved. Default: `overview-analytics.md`.
 279
 280        See also: `Overview()` with parameter `details="analytics"`.
 281        """
 282
 283        self.overviewBondsCalendarFile = "overview-calendar.md"
 284        """Filename where only the bonds calendar section will be saved. Default: `overview-calendar.md`.
 285
 286        See also: `Overview()` with parameter `details="calendar"`.
 287        """
 288
 289        self.reportFile = "deals.md"
 290        """Filename where history of deals and trade statistics will be saved. Default: `deals.md`.
 291
 292        See also: `Deals()`.
 293        """
 294
 295        self.withdrawalLimitsFile = "limits.md"
 296        """Filename where table of funds available for withdrawal will be saved. Default: `limits.md`.
 297
 298        See also: `OverviewLimits()` and `RequestLimits()`.
 299        """
 300
 301        self.userInfoFile = "user-info.md"
 302        """Filename where all available user's data (`accountId`s, common user information, margin status and tariff connections limit) will be saved. Default: `user-info.md`.
 303
 304        See also: `OverviewUserInfo()`, `RequestAccounts()`, `RequestUserInfo()`, `RequestMarginStatus()` and `RequestTariffLimits()`.
 305        """
 306
 307        self.userAccountsFile = "accounts.md"
 308        """Filename where simple table with all available user accounts (`accountId`s) will be saved. Default: `accounts.md`.
 309
 310        See also: `OverviewAccounts()`, `RequestAccounts()`.
 311        """
 312
 313        self.iListDumpFile = "dump.json" if defaultCache is None or not isinstance(defaultCache, str) or not defaultCache else defaultCache
 314        """Filename where raw data about shares, currencies, bonds, etfs and futures will be stored. Default: `dump.json`.
 315
 316        Pandas dataframe with raw instruments data also will be stored to default file `dump.xlsx`.
 317
 318        See also: `DumpInstruments()` and `DumpInstrumentsAsXLSX()`.
 319        """
 320
 321        self.iList = None  # init iList for raw instruments data
 322        """Dictionary with raw data about shares, currencies, bonds, etfs and futures from broker server. Auto-updating and saving dump to the `iListDumpFile`.
 323        
 324        See also: `Listing()`, `DumpInstruments()`.
 325        """
 326
 327        # trying to re-load raw instruments data from file `iListDumpFile` or try to update it from server:
 328        if useCache:
 329            if os.path.exists(self.iListDumpFile):
 330                dumpTime = datetime.fromtimestamp(os.path.getmtime(self.iListDumpFile)).astimezone(tzutc())  # dump modification date and time
 331                curTime = datetime.now(tzutc())
 332
 333                if (curTime.day > dumpTime.day) or (curTime.month > dumpTime.month) or (curTime.year > dumpTime.year):
 334                    uLogger.warning("Local cache may be outdated! It has last modified [{}] UTC. Updating from broker server, wait, please...".format(dumpTime.strftime(TKS_PRINT_DATE_TIME_FORMAT)))
 335
 336                    self.DumpInstruments(forceUpdate=True)  # updating self.iList and dump file
 337
 338                else:
 339                    self.iList = json.load(open(self.iListDumpFile, mode="r", encoding="UTF-8"))  # load iList from dump
 340
 341                    uLogger.debug("Local cache with raw instruments data is used: [{}]. Last modified: [{}] UTC".format(
 342                        os.path.abspath(self.iListDumpFile),
 343                        dumpTime.strftime(TKS_PRINT_DATE_TIME_FORMAT),
 344                    ))
 345
 346            else:
 347                uLogger.warning("Local cache with raw instruments data not exists! Creating new dump, wait, please...")
 348                self.DumpInstruments(forceUpdate=True)  # updating self.iList and creating default dump file
 349
 350        else:
 351            self.iList = self.Listing()  # request new raw instruments data from broker server
 352            self.DumpInstruments(forceUpdate=False)  # save raw instrument's data to default dump file `iListDumpFile`
 353
 354        self.priceModel = PriceGenerator()  # init PriceGenerator object to work with candles data
 355        """PriceGenerator object to work with candles data: load, render interact and non-interact charts and so on.
 356
 357        See also: `LoadHistory()`, `ShowHistoryChart()` and the PriceGenerator project: https://github.com/Tim55667757/PriceGenerator
 358        """
 359
 360    @property
 361    def ticker(self) -> str:
 362        """String with ticker, e.g. `GOOGL`. Tickers may be upper case only.
 363
 364        Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR` etc.
 365        More tickers aliases here: `TKSEnums.TKS_TICKER_ALIASES`.
 366
 367        See also: `SearchByTicker()`, `SearchInstruments()`.
 368        """
 369        return self._ticker
 370
 371    @ticker.setter
 372    def ticker(self, value):
 373        """Setter for string with ticker, e.g. `GOOGL`. Tickers may be upper case only.
 374
 375        Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR` etc.
 376        More tickers aliases here: `TKSEnums.TKS_TICKER_ALIASES`.
 377
 378        See also: `SearchByTicker()`, `SearchInstruments()`.
 379        """
 380        self._ticker = str(value).upper()  # Tickers may be upper case only
 381
 382    @property
 383    def figi(self) -> str:
 384        """String with FIGI, e.g. ticker `GOOGL` has FIGI `BBG009S39JX6`. FIGIs may be upper case only.
 385
 386        See also: `SearchByFIGI()`, `SearchInstruments()`.
 387        """
 388        return self._figi
 389
 390    @figi.setter
 391    def figi(self, value):
 392        """Setter for string with FIGI, e.g. ticker `GOOGL` has FIGI `BBG009S39JX6`. FIGIs may be upper case only.
 393
 394        See also: `SearchByFIGI()`, `SearchInstruments()`.
 395        """
 396        self._figi = str(value).upper()  # FIGI may be upper case only
 397
 398    def _ParseJSON(self, rawData="{}") -> dict:
 399        """
 400        Parse JSON from response string.
 401
 402        :param rawData: this is a string with JSON-formatted text.
 403        :return: JSON (dictionary), parsed from server response string. If an error occurred, then returns empty dict `{}`.
 404        """
 405        try:
 406            responseJSON = json.loads(rawData) if rawData else {}
 407
 408            if self.moreDebug:
 409                uLogger.debug("JSON formatted raw body data of response:\n{}".format(json.dumps(responseJSON, indent=4)))
 410
 411            return responseJSON
 412
 413        except Exception as e:
 414            uLogger.error("An empty dict will be return, because an error occurred in `_ParseJSON()` method with comment: {}".format(e))
 415            return {}
 416
 417    def SendAPIRequest(self, url: str, reqType: str = "GET", retry: int = 3, pause: int = 5) -> dict:
 418        """
 419        Send GET or POST request to broker server and receive JSON object.
 420
 421        self.header: must be defining with dictionary of headers.
 422        self.body: if define then used as request body. None by default.
 423        self.timeout: global request timeout, 15 seconds by default.
 424        :param url: url with REST request.
 425        :param reqType: send "GET" or "POST" request. "GET" by default.
 426        :param retry: how many times retry after first request if an 5xx server errors occurred.
 427        :param pause: sleep time in seconds between retries.
 428        :return: response JSON (dictionary) from broker.
 429        """
 430        if reqType.upper() not in ("GET", "POST"):
 431            uLogger.error("You can define request type: `GET` or `POST`!")
 432            raise Exception("Incorrect value")
 433
 434        if self.moreDebug:
 435            uLogger.debug("Request parameters:")
 436            uLogger.debug("    - REST API URL: {}".format(url))
 437            uLogger.debug("    - request type: {}".format(reqType))
 438            uLogger.debug("    - headers:\n{}".format(str(self.headers).replace(self.token, "*** request token ***")))
 439            uLogger.debug("    - body:\n{}".format(self.body))
 440
 441        # fast hack to avoid all operations with some tickers/FIGI
 442        responseJSON = {}
 443        oK = True
 444        for item in self.exclude:
 445            if item in url:
 446                if self.moreDebug:
 447                    uLogger.warning("Do not execute operations with list of this tickers/FIGI: {}".format(str(self.exclude)))
 448
 449                oK = False
 450                break
 451
 452        if oK:
 453            with self.__lock:  # acquire the mutex lock
 454                counter = 0
 455                response = None
 456                errMsg = ""
 457
 458                while not response and counter <= retry:
 459                    if reqType == "GET":
 460                        response = requests.get(url, headers=self.headers, data=self.body, timeout=self.timeout)
 461
 462                    if reqType == "POST":
 463                        response = requests.post(url, headers=self.headers, data=self.body, timeout=self.timeout)
 464
 465                    if self.moreDebug:
 466                        uLogger.debug("Response:")
 467                        uLogger.debug("    - status code: {}".format(response.status_code))
 468                        uLogger.debug("    - reason: {}".format(response.reason))
 469                        uLogger.debug("    - body length: {}".format(len(response.text)))
 470                        uLogger.debug("    - headers:\n{}".format(response.headers))
 471
 472                    # Server returns some headers:
 473                    # - `x-ratelimit-limit` — shows the settings of the current user limit for this method.
 474                    # - `x-ratelimit-remaining` — the number of remaining requests of this type per minute.
 475                    # - `x-ratelimit-reset` — time in seconds before resetting the request counter.
 476                    # See: https://tinkoff.github.io/investAPI/grpc/#kreya
 477                    if "x-ratelimit-remaining" in response.headers.keys() and response.headers["x-ratelimit-remaining"] == "0":
 478                        rateLimitWait = int(response.headers["x-ratelimit-reset"])
 479                        uLogger.debug("Rate limit exceeded. Waiting {} sec. for reset rate limit and then repeat again...".format(rateLimitWait))
 480                        sleep(rateLimitWait)
 481
 482                    # Error status codes: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
 483                    if 400 <= response.status_code < 500:
 484                        msg = "status code: [{}], response body: {}".format(response.status_code, response.text)
 485                        uLogger.debug("    - not oK, but do not retry for 4xx errors, {}".format(msg))
 486
 487                        if "code" in response.text and "message" in response.text:
 488                            msgDict = self._ParseJSON(rawData=response.text)
 489                            uLogger.warning("HTTP-status code [{}], server message: {}".format(response.status_code, msgDict["message"]))
 490
 491                        counter = retry + 1  # do not retry for 4xx errors
 492
 493                    if 500 <= response.status_code < 600:
 494                        errMsg = "status code: [{}], response body: {}".format(response.status_code, response.text)
 495                        uLogger.debug("    - not oK, {}".format(errMsg))
 496
 497                        if "code" in response.text and "message" in response.text:
 498                            errMsgDict = self._ParseJSON(rawData=response.text)
 499                            uLogger.warning("HTTP-status code [{}], error message: {}".format(response.status_code, errMsgDict["message"]))
 500
 501                        counter += 1
 502
 503                        if counter <= retry:
 504                            uLogger.debug("Retry: [{}]. Wait {} sec. and try again...".format(counter, pause))
 505                            sleep(pause)
 506
 507                responseJSON = self._ParseJSON(rawData=response.text)
 508
 509                if errMsg:
 510                    uLogger.error("Server returns not `oK` status! See: https://tinkoff.github.io/investAPI/errors/")
 511                    uLogger.error("    - not oK, {}".format(errMsg))
 512
 513        return responseJSON
 514
 515    def _IUpdater(self, iType: str) -> tuple:
 516        """
 517        Request instrument by type from server. See available API methods for instruments:
 518        Currencies: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Currencies
 519        Shares: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Shares
 520        Bonds: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Bonds
 521        Etfs: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Etfs
 522        Futures: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Futures
 523
 524        :param iType: type of the instrument, it must be one of supported types in TKS_INSTRUMENTS list.
 525        :return: tuple with iType name and list of available instruments of current type for defined user token.
 526        """
 527        result = []
 528
 529        if iType in TKS_INSTRUMENTS:
 530            uLogger.debug("Requesting available [{}] list. Wait, please...".format(iType))
 531
 532            # all instruments have the same body in API v2 requests:
 533            self.body = str({"instrumentStatus": "INSTRUMENT_STATUS_UNSPECIFIED"})  # Enum: [INSTRUMENT_STATUS_UNSPECIFIED, INSTRUMENT_STATUS_BASE, INSTRUMENT_STATUS_ALL]
 534            instrumentURL = self.server + r"/tinkoff.public.invest.api.contract.v1.InstrumentsService/{}".format(iType)
 535            result = self.SendAPIRequest(instrumentURL, reqType="POST")["instruments"]
 536
 537        return iType, result
 538
 539    def _IWrapper(self, kwargs):
 540        """
 541        Wrapper runs instrument's update method `_IUpdater()`.
 542        It's a workaround for using multiprocessing with kwargs. See: https://stackoverflow.com/a/36799206
 543        """
 544        return self._IUpdater(**kwargs)
 545
 546    def Listing(self) -> dict:
 547        """
 548        Gets JSON with raw data about shares, currencies, bonds, etfs and futures from broker server.
 549
 550        :return: Dictionary with all available broker instruments: currencies, shares, bonds, etfs and futures.
 551        """
 552        uLogger.debug("Requesting all available instruments for current account. Wait, please...")
 553        uLogger.debug("CPU usages for parallel requests: [{}]".format(CPU_USAGES))
 554
 555        # this parameters insert to requests: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService
 556        # iType is type of instrument, it must be one of supported types in TKS_INSTRUMENTS list.
 557        iParams = [{"iType": iType} for iType in TKS_INSTRUMENTS]
 558
 559        poolUpdater = ThreadPool(processes=CPU_USAGES)  # create pool for update instruments in parallel mode
 560        listing = poolUpdater.map(self._IWrapper, iParams)  # execute update operations
 561        poolUpdater.close()  # close the thread pool
 562        poolUpdater.join()  # wait a moment until all data returns from threads
 563
 564        # Dictionary with all broker instruments: shares, currencies, bonds, etfs and futures.
 565        # Next in this code: item[0] is "iType" and item[1] is list of available instruments from the result of _IUpdater() method
 566        iList = {item[0]: {instrument["ticker"]: instrument for instrument in item[1]} for item in listing}
 567
 568        # calculate minimum price increment (step) for all instruments and set up instrument's type:
 569        for iType in iList.keys():
 570            for ticker in iList[iType]:
 571                iList[iType][ticker]["type"] = iType
 572
 573                if "minPriceIncrement" in iList[iType][ticker].keys():
 574                    iList[iType][ticker]["step"] = NanoToFloat(
 575                        iList[iType][ticker]["minPriceIncrement"]["units"],
 576                        iList[iType][ticker]["minPriceIncrement"]["nano"],
 577                    )
 578
 579                else:
 580                    iList[iType][ticker]["step"] = 0  # hack to avoid empty value in some instruments, e.g. futures
 581
 582        return iList
 583
 584    def DumpInstrumentsAsXLSX(self, forceUpdate: bool = False) -> None:
 585        """
 586        Creates XLSX-formatted dump file with raw data of instruments to further used by data scientists or stock analytics.
 587
 588        See also: `DumpInstruments()`, `Listing()`.
 589
 590        :param forceUpdate: if `True` then at first updates data with `Listing()` method,
 591                            otherwise just saves exist `iList` as XLSX-file (default: `dump.xlsx`) .
 592        """
 593        if self.iListDumpFile is None or not self.iListDumpFile:
 594            uLogger.error("Output name of dump file must be defined!")
 595            raise Exception("Filename required")
 596
 597        if not self.iList or forceUpdate:
 598            self.iList = self.Listing()
 599
 600        xlsxDumpFile = self.iListDumpFile.replace(".json", ".xlsx") if self.iListDumpFile.endswith(".json") else self.iListDumpFile + ".xlsx"
 601
 602        # Save as XLSX with separated sheets for every type of instruments:
 603        with pd.ExcelWriter(
 604                path=xlsxDumpFile,
 605                date_format=TKS_DATE_FORMAT,
 606                datetime_format=TKS_DATE_TIME_FORMAT,
 607                mode="w",
 608        ) as writer:
 609            for iType in TKS_INSTRUMENTS:
 610                df = pd.DataFrame.from_dict(data=self.iList[iType], orient="index")  # generate pandas object from self.iList dictionary
 611                df = df[sorted(df)]  # sorted by column names
 612                df = df.applymap(
 613                    lambda item: NanoToFloat(item["units"], item["nano"]) if isinstance(item, dict) and "units" in item.keys() and "nano" in item.keys() else item,
 614                    na_action="ignore",
 615                )  # converting numbers from nano-type to float in every cell
 616                df.to_excel(
 617                    writer,
 618                    sheet_name=iType,
 619                    encoding="UTF-8",
 620                    freeze_panes=(1, 1),
 621                )  # saving as XLSX-file with freeze first row and column as headers
 622
 623        uLogger.info("XLSX-file for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(xlsxDumpFile)))
 624
 625    def DumpInstruments(self, forceUpdate: bool = True) -> str:
 626        """
 627        Receives and returns actual raw data about shares, currencies, bonds, etfs and futures from broker server
 628        using `Listing()` method. If `iListDumpFile` string is not empty then also save information to this file.
 629
 630        See also: `DumpInstrumentsAsXLSX()`, `Listing()`.
 631
 632        :param forceUpdate: if `True` then at first updates data with `Listing()` method,
 633                            otherwise just saves exist `iList` as JSON-file (default: `dump.json`).
 634        :return: serialized JSON formatted `str` with full data of instruments, also saved to the `--output` JSON-file.
 635        """
 636        if self.iListDumpFile is None or not self.iListDumpFile:
 637            uLogger.error("Output name of dump file must be defined!")
 638            raise Exception("Filename required")
 639
 640        if not self.iList or forceUpdate:
 641            self.iList = self.Listing()
 642
 643        jsonDump = json.dumps(self.iList, indent=4, sort_keys=False)  # create JSON object as string
 644        with open(self.iListDumpFile, mode="w", encoding="UTF-8") as fH:
 645            fH.write(jsonDump)
 646
 647        uLogger.info("New cache of instruments data was created: [{}]".format(os.path.abspath(self.iListDumpFile)))
 648
 649        return jsonDump
 650
 651    def ShowInstrumentInfo(self, iJSON: dict, show: bool = True) -> str:
 652        """
 653        Show information about one instrument defined by json data and prints it in Markdown format.
 654
 655        See also: `SearchByTicker()`, `SearchByFIGI()`, `RequestBondCoupons()`, `ExtendBondsData()`, `ShowBondsCalendar()` and `RequestTradingStatus()`.
 656
 657        :param iJSON: json data of instrument, example: `iJSON = self.iList["Shares"][self._ticker]`
 658        :param show: if `True` then also printing information about instrument and its current price.
 659        :return: multilines text in Markdown format with information about one instrument.
 660        """
 661        splitLine = "|                                                             |                                                        |\n"
 662        infoText = ""
 663
 664        if iJSON is not None and iJSON and isinstance(iJSON, dict):
 665            info = [
 666                "# Main information\n\n",
 667                "* **Actual on date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
 668                "| Parameters                                                  | Values                                                 |\n",
 669                "|-------------------------------------------------------------|--------------------------------------------------------|\n",
 670                "| Ticker:                                                     | {:<54} |\n".format(iJSON["ticker"]),
 671                "| Full name:                                                  | {:<54} |\n".format(iJSON["name"]),
 672            ]
 673
 674            if "sector" in iJSON.keys() and iJSON["sector"]:
 675                info.append("| Sector:                                                     | {:<54} |\n".format(iJSON["sector"]))
 676
 677            if "countryOfRisk" in iJSON.keys() and iJSON["countryOfRisk"] and "countryOfRiskName" in iJSON.keys() and iJSON["countryOfRiskName"]:
 678                info.append("| Country of instrument:                                      | {:<54} |\n".format("({}) {}".format(iJSON["countryOfRisk"], iJSON["countryOfRiskName"])))
 679
 680            info.extend([
 681                splitLine,
 682                "| FIGI (Financial Instrument Global Identifier):              | {:<54} |\n".format(iJSON["figi"]),
 683                "| Real exchange [Exchange section]:                           | {:<54} |\n".format("{} [{}]".format(TKS_REAL_EXCHANGES[iJSON["realExchange"]], iJSON["exchange"])),
 684            ])
 685
 686            if "isin" in iJSON.keys() and iJSON["isin"]:
 687                info.append("| ISIN (International Securities Identification Number):      | {:<54} |\n".format(iJSON["isin"]))
 688
 689            if "classCode" in iJSON.keys():
 690                info.append("| Class Code (exchange section where instrument is traded):   | {:<54} |\n".format(iJSON["classCode"]))
 691
 692            info.extend([
 693                splitLine,
 694                "| Current broker security trading status:                     | {:<54} |\n".format(TKS_TRADING_STATUSES[iJSON["tradingStatus"]]),
 695                splitLine,
 696                "| Buy operations allowed:                                     | {:<54} |\n".format("Yes" if iJSON["buyAvailableFlag"] else "No"),
 697                "| Sale operations allowed:                                    | {:<54} |\n".format("Yes" if iJSON["sellAvailableFlag"] else "No"),
 698                "| Short positions allowed:                                    | {:<54} |\n".format("Yes" if iJSON["shortEnabledFlag"] else "No"),
 699            ])
 700
 701            if iJSON["figi"]:
 702                self._figi = iJSON["figi"]
 703                iJSON = iJSON | self.RequestTradingStatus()
 704
 705                info.extend([
 706                    splitLine,
 707                    "| Limit orders allowed:                                       | {:<54} |\n".format("Yes" if iJSON["limitOrderAvailableFlag"] else "No"),
 708                    "| Market orders allowed:                                      | {:<54} |\n".format("Yes" if iJSON["marketOrderAvailableFlag"] else "No"),
 709                    "| API trade allowed:                                          | {:<54} |\n".format("Yes" if iJSON["apiTradeAvailableFlag"] else "No"),
 710                ])
 711
 712            info.append(splitLine)
 713
 714            if "type" in iJSON.keys() and iJSON["type"]:
 715                info.append("| Type of the instrument:                                     | {:<54} |\n".format(iJSON["type"]))
 716
 717                if "shareType" in iJSON.keys() and iJSON["shareType"]:
 718                    info.append("| Share type:                                                 | {:<54} |\n".format(TKS_SHARE_TYPES[iJSON["shareType"]]))
 719
 720            if "futuresType" in iJSON.keys() and iJSON["futuresType"]:
 721                info.append("| Futures type:                                               | {:<54} |\n".format(iJSON["futuresType"]))
 722
 723            if "ipoDate" in iJSON.keys() and iJSON["ipoDate"]:
 724                info.append("| IPO date:                                                   | {:<54} |\n".format(iJSON["ipoDate"].replace("T", " ").replace("Z", "")))
 725
 726            if "releasedDate" in iJSON.keys() and iJSON["releasedDate"]:
 727                info.append("| Released date:                                              | {:<54} |\n".format(iJSON["releasedDate"].replace("T", " ").replace("Z", "")))
 728
 729            if "rebalancingFreq" in iJSON.keys() and iJSON["rebalancingFreq"]:
 730                info.append("| Rebalancing frequency:                                      | {:<54} |\n".format(iJSON["rebalancingFreq"]))
 731
 732            if "focusType" in iJSON.keys() and iJSON["focusType"]:
 733                info.append("| Focusing type:                                              | {:<54} |\n".format(iJSON["focusType"]))
 734
 735            if "assetType" in iJSON.keys() and iJSON["assetType"]:
 736                info.append("| Asset type:                                                 | {:<54} |\n".format(iJSON["assetType"]))
 737
 738            if "basicAsset" in iJSON.keys() and iJSON["basicAsset"]:
 739                info.append("| Basic asset:                                                | {:<54} |\n".format(iJSON["basicAsset"]))
 740
 741            if "basicAssetSize" in iJSON.keys() and iJSON["basicAssetSize"]:
 742                info.append("| Basic asset size:                                           | {:<54} |\n".format("{:.2f}".format(NanoToFloat(str(iJSON["basicAssetSize"]["units"]), iJSON["basicAssetSize"]["nano"]))))
 743
 744            if "isoCurrencyName" in iJSON.keys() and iJSON["isoCurrencyName"]:
 745                info.append("| ISO currency name:                                          | {:<54} |\n".format(iJSON["isoCurrencyName"]))
 746
 747            if "currency" in iJSON.keys():
 748                info.append("| Payment currency:                                           | {:<54} |\n".format(iJSON["currency"]))
 749
 750            if iJSON["type"] == "Bonds" and "nominal" in iJSON.keys() and "currency" in iJSON["nominal"].keys():
 751                info.append("| Nominal currency:                                           | {:<54} |\n".format(iJSON["nominal"]["currency"]))
 752
 753            if "firstTradeDate" in iJSON.keys() and iJSON["firstTradeDate"]:
 754                info.append("| First trade date:                                           | {:<54} |\n".format(iJSON["firstTradeDate"].replace("T", " ").replace("Z", "")))
 755
 756            if "lastTradeDate" in iJSON.keys() and iJSON["lastTradeDate"]:
 757                info.append("| Last trade date:                                            | {:<54} |\n".format(iJSON["lastTradeDate"].replace("T", " ").replace("Z", "")))
 758
 759            if "expirationDate" in iJSON.keys() and iJSON["expirationDate"]:
 760                info.append("| Date of expiration:                                         | {:<54} |\n".format(iJSON["expirationDate"].replace("T", " ").replace("Z", "")))
 761
 762            if "stateRegDate" in iJSON.keys() and iJSON["stateRegDate"]:
 763                info.append("| State registration date:                                    | {:<54} |\n".format(iJSON["stateRegDate"].replace("T", " ").replace("Z", "")))
 764
 765            if "placementDate" in iJSON.keys() and iJSON["placementDate"]:
 766                info.append("| Placement date:                                             | {:<54} |\n".format(iJSON["placementDate"].replace("T", " ").replace("Z", "")))
 767
 768            if "maturityDate" in iJSON.keys() and iJSON["maturityDate"]:
 769                info.append("| Maturity date:                                              | {:<54} |\n".format(iJSON["maturityDate"].replace("T", " ").replace("Z", "")))
 770
 771            if "perpetualFlag" in iJSON.keys() and iJSON["perpetualFlag"]:
 772                info.append("| Perpetual bond:                                             | Yes                                                    |\n")
 773
 774            if "otcFlag" in iJSON.keys() and iJSON["otcFlag"]:
 775                info.append("| Over-the-counter (OTC) securities:                          | Yes                                                    |\n")
 776
 777            iExt = None
 778            if iJSON["type"] == "Bonds":
 779                info.extend([
 780                    splitLine,
 781                    "| Bond issue (size / plan):                                   | {:<54} |\n".format("{} / {}".format(iJSON["issueSize"], iJSON["issueSizePlan"])),
 782                    "| Nominal price (100%):                                       | {:<54} |\n".format("{} {}".format(
 783                        "{:.2f}".format(NanoToFloat(str(iJSON["nominal"]["units"]), iJSON["nominal"]["nano"])).rstrip("0").rstrip("."),
 784                        iJSON["nominal"]["currency"],
 785                    )),
 786                ])
 787
 788                if "floatingCouponFlag" in iJSON.keys():
 789                    info.append("| Floating coupon:                                            | {:<54} |\n".format("Yes" if iJSON["floatingCouponFlag"] else "No"))
 790
 791                if "amortizationFlag" in iJSON.keys():
 792                    info.append("| Amortization:                                               | {:<54} |\n".format("Yes" if iJSON["amortizationFlag"] else "No"))
 793
 794                info.append(splitLine)
 795
 796                if "couponQuantityPerYear" in iJSON.keys() and iJSON["couponQuantityPerYear"]:
 797                    info.append("| Number of coupon payments per year:                         | {:<54} |\n".format(iJSON["couponQuantityPerYear"]))
 798
 799                if iJSON["figi"]:
 800                    iExt = self.ExtendBondsData(instruments=iJSON["figi"], xlsx=False)  # extended bonds data
 801
 802                    info.extend([
 803                        "| Days last to maturity date:                                 | {:<54} |\n".format(iExt["daysToMaturity"][0]),
 804                        "| Coupons yield (average coupon daily yield * 365):           | {:<54} |\n".format("{:.2f}%".format(iExt["couponsYield"][0])),
 805                        "| Current price yield (average daily yield * 365):            | {:<54} |\n".format("{:.2f}%".format(iExt["currentYield"][0])),
 806                    ])
 807
 808                if "aciValue" in iJSON.keys() and iJSON["aciValue"]:
 809                    info.append("| Current accumulated coupon income (ACI):                    | {:<54} |\n".format("{:.2f} {}".format(
 810                        NanoToFloat(str(iJSON["aciValue"]["units"]), iJSON["aciValue"]["nano"]),
 811                        iJSON["aciValue"]["currency"]
 812                    )))
 813
 814            if "currentPrice" in iJSON.keys():
 815                info.append(splitLine)
 816
 817                currency = iJSON["currency"] if "currency" in iJSON.keys() else ""  # nominal currency for bonds, otherwise currency of instrument
 818                aciCurrency = iExt["aciCurrency"][0] if iJSON["type"] == "Bonds" and iExt is not None and "aciCurrency" in iExt.keys() else ""  # payment currency
 819
 820                bondPrevClose = iExt["closePrice"][0] if iJSON["type"] == "Bonds" and iExt is not None and "closePrice" in iExt.keys() else 0  # previous close price of bond
 821                bondLastPrice = iExt["lastPrice"][0] if iJSON["type"] == "Bonds" and iExt is not None and "lastPrice" in iExt.keys() else 0  # last price of bond
 822                bondLimitUp = iExt["limitUp"][0] if iJSON["type"] == "Bonds" and iExt is not None and "limitUp" in iExt.keys() else 0  # max price of bond
 823                bondLimitDown = iExt["limitDown"][0] if iJSON["type"] == "Bonds" and iExt is not None and "limitDown" in iExt.keys() else 0  # min price of bond
 824                bondChangesDelta = iExt["changesDelta"][0] if iJSON["type"] == "Bonds" and iExt is not None and "changesDelta" in iExt.keys() else 0  # delta between last deal price and last close
 825
 826                curPriceSell = iJSON["currentPrice"]["sell"][0]["price"] if iJSON["currentPrice"]["sell"] else 0
 827                curPriceBuy = iJSON["currentPrice"]["buy"][0]["price"] if iJSON["currentPrice"]["buy"] else 0
 828
 829                info.extend([
 830                    "| Previous close price of the instrument:                     | {:<54} |\n".format("{}{}".format(
 831                        "{}".format(iJSON["currentPrice"]["closePrice"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["closePrice"] is not None else "N/A",
 832                        "% of nominal price ({:.2f} {})".format(bondPrevClose, aciCurrency) if iJSON["type"] == "Bonds" else " {}".format(currency),
 833                    )),
 834                    "| Last deal price of the instrument:                          | {:<54} |\n".format("{}{}".format(
 835                        "{}".format(iJSON["currentPrice"]["lastPrice"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["lastPrice"] is not None else "N/A",
 836                        "% of nominal price ({:.2f} {})".format(bondLastPrice, aciCurrency) if iJSON["type"] == "Bonds" else " {}".format(currency),
 837                    )),
 838                    "| Changes between last deal price and last close              | {:<54} |\n".format(
 839                        "{:.2f}%{}".format(
 840                            iJSON["currentPrice"]["changes"],
 841                            " ({}{:.2f} {})".format(
 842                                "+" if bondChangesDelta > 0 else "",
 843                                bondChangesDelta,
 844                                aciCurrency
 845                            ) if iJSON["type"] == "Bonds" else " ({}{:.2f} {})".format(
 846                                "+" if iJSON["currentPrice"]["lastPrice"] > iJSON["currentPrice"]["closePrice"] else "",
 847                                iJSON["currentPrice"]["lastPrice"] - iJSON["currentPrice"]["closePrice"],
 848                                currency
 849                            ),
 850                        )
 851                    ),
 852                    "| Current limit price, min / max:                             | {:<54} |\n".format("{}{} / {}{}{}".format(
 853                        "{}".format(iJSON["currentPrice"]["limitDown"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["limitDown"] is not None else "N/A",
 854                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 855                        "{}".format(iJSON["currentPrice"]["limitUp"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["limitUp"] is not None else "N/A",
 856                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 857                        " ({:.2f} {} / {:.2f} {})".format(bondLimitDown, aciCurrency, bondLimitUp, aciCurrency) if iJSON["type"] == "Bonds" else ""
 858                    )),
 859                    "| Actual price, sell / buy:                                   | {:<54} |\n".format("{}{} / {}{}{}".format(
 860                        "{}".format(curPriceSell).rstrip("0").rstrip(".") if curPriceSell != 0 else "N/A",
 861                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 862                        "{}".format(curPriceBuy).rstrip("0").rstrip(".") if curPriceBuy != 0 else "N/A",
 863                        "%" if iJSON["type"] == "Bonds" else" {}".format(currency),
 864                        " ({:.2f} {} / {:.2f} {})".format(curPriceSell, aciCurrency, curPriceBuy, aciCurrency) if iJSON["type"] == "Bonds" else ""
 865                    )),
 866                ])
 867
 868            if "lot" in iJSON.keys():
 869                info.append("| Minimum lot to buy:                                         | {:<54} |\n".format(iJSON["lot"]))
 870
 871            if "step" in iJSON.keys() and iJSON["step"] != 0:
 872                info.append("| Minimum price increment (step):                             | {:<54} |\n".format("{} {}".format(iJSON["step"], iJSON["currency"] if "currency" in iJSON.keys() else "")))
 873
 874            # Add bond payment calendar:
 875            if iJSON["type"] == "Bonds":
 876                strCalendar = self.ShowBondsCalendar(extBonds=iExt, show=False)   # bond payment calendar
 877                info.extend(["\n#", strCalendar])
 878
 879            infoText += "".join(info)
 880
 881            if show:
 882                uLogger.info("{}".format(infoText))
 883
 884            else:
 885                uLogger.debug("{}".format(infoText))
 886
 887            if self.infoFile is not None:
 888                with open(self.infoFile, "w", encoding="UTF-8") as fH:
 889                    fH.write(infoText)
 890
 891                uLogger.info("Info about instrument with ticker [{}] and FIGI [{}] was saved to file: [{}]".format(iJSON["ticker"], iJSON["figi"], os.path.abspath(self.infoFile)))
 892
 893                if self.useHTMLReports:
 894                    htmlFilePath = self.infoFile.replace(".md", ".html") if self.infoFile.endswith(".md") else self.infoFile + ".html"
 895                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
 896                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Main information", commonCSS=COMMON_CSS, markdown=infoText))
 897
 898                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
 899
 900        return infoText
 901
 902    def SearchByTicker(self, requestPrice: bool = False, show: bool = False) -> dict:
 903        """
 904        Search and return raw broker's information about instrument by its ticker. Variable `ticker` must be defined!
 905
 906        :param requestPrice: if `False` then do not request current price of instrument (because this is long operation).
 907        :param show: if `False` then do not run `ShowInstrumentInfo()` method and do not print info to the console.
 908        :return: JSON formatted data with information about instrument.
 909        """
 910        tickerJSON = {}
 911        if self.moreDebug:
 912            uLogger.debug("Searching information about instrument by it's ticker [{}] ...".format(self._ticker))
 913
 914        if not self._ticker:
 915            uLogger.warning("self._ticker variable is not be empty!")
 916
 917        else:
 918            if self._ticker in TKS_TICKERS_OR_FIGI_EXCLUDED:
 919                uLogger.warning("Instrument with ticker [{}] not allowed for trading!".format(self._ticker))
 920                raise Exception("Instrument not allowed")
 921
 922            if not self.iList:
 923                self.iList = self.Listing()
 924
 925            if self._ticker in self.iList["Shares"].keys():
 926                tickerJSON = self.iList["Shares"][self._ticker]
 927                if self.moreDebug:
 928                    uLogger.debug("Ticker [{}] found in shares list".format(self._ticker))
 929
 930            elif self._ticker in self.iList["Currencies"].keys():
 931                tickerJSON = self.iList["Currencies"][self._ticker]
 932                if self.moreDebug:
 933                    uLogger.debug("Ticker [{}] found in currencies list".format(self._ticker))
 934
 935            elif self._ticker in self.iList["Bonds"].keys():
 936                tickerJSON = self.iList["Bonds"][self._ticker]
 937                if self.moreDebug:
 938                    uLogger.debug("Ticker [{}] found in bonds list".format(self._ticker))
 939
 940            elif self._ticker in self.iList["Etfs"].keys():
 941                tickerJSON = self.iList["Etfs"][self._ticker]
 942                if self.moreDebug:
 943                    uLogger.debug("Ticker [{}] found in etfs list".format(self._ticker))
 944
 945            elif self._ticker in self.iList["Futures"].keys():
 946                tickerJSON = self.iList["Futures"][self._ticker]
 947                if self.moreDebug:
 948                    uLogger.debug("Ticker [{}] found in futures list".format(self._ticker))
 949
 950        if tickerJSON:
 951            self._figi = tickerJSON["figi"]
 952
 953            if requestPrice:
 954                tickerJSON["currentPrice"] = self.GetCurrentPrices(show=False)
 955
 956                if tickerJSON["currentPrice"]["closePrice"] is not None and tickerJSON["currentPrice"]["closePrice"] != 0 and tickerJSON["currentPrice"]["lastPrice"] is not None:
 957                    tickerJSON["currentPrice"]["changes"] = 100 * (tickerJSON["currentPrice"]["lastPrice"] - tickerJSON["currentPrice"]["closePrice"]) / tickerJSON["currentPrice"]["closePrice"]
 958
 959                else:
 960                    tickerJSON["currentPrice"]["changes"] = 0
 961
 962            if show:
 963                self.ShowInstrumentInfo(iJSON=tickerJSON, show=True)  # print info as Markdown text
 964
 965        else:
 966            if show:
 967                uLogger.warning("Ticker [{}] not found in available broker instrument's list!".format(self._ticker))
 968
 969        return tickerJSON
 970
 971    def SearchByFIGI(self, requestPrice: bool = False, show: bool = False) -> dict:
 972        """
 973        Search and return raw broker's information about instrument by its FIGI. Variable `figi` must be defined!
 974
 975        :param requestPrice: if `False` then do not request current price of instrument (it's long operation).
 976        :param show: if `False` then do not run `ShowInstrumentInfo()` method and do not print info to the console.
 977        :return: JSON formatted data with information about instrument.
 978        """
 979        figiJSON = {}
 980        if self.moreDebug:
 981            uLogger.debug("Searching information about instrument by it's FIGI [{}] ...".format(self._figi))
 982
 983        if not self._figi:
 984            uLogger.warning("self._figi variable is not be empty!")
 985
 986        else:
 987            if self._figi in TKS_TICKERS_OR_FIGI_EXCLUDED:
 988                uLogger.warning("Instrument with figi [{}] not allowed for trading!".format(self._figi))
 989                raise Exception("Instrument not allowed")
 990
 991            if not self.iList:
 992                self.iList = self.Listing()
 993
 994            for item in self.iList["Shares"].keys():
 995                if self._figi == self.iList["Shares"][item]["figi"]:
 996                    figiJSON = self.iList["Shares"][item]
 997
 998                    if self.moreDebug:
 999                        uLogger.debug("FIGI [{}] found in shares list".format(self._figi))
1000
1001                    break
1002
1003            if not figiJSON:
1004                for item in self.iList["Currencies"].keys():
1005                    if self._figi == self.iList["Currencies"][item]["figi"]:
1006                        figiJSON = self.iList["Currencies"][item]
1007
1008                        if self.moreDebug:
1009                            uLogger.debug("FIGI [{}] found in currencies list".format(self._figi))
1010
1011                        break
1012
1013            if not figiJSON:
1014                for item in self.iList["Bonds"].keys():
1015                    if self._figi == self.iList["Bonds"][item]["figi"]:
1016                        figiJSON = self.iList["Bonds"][item]
1017
1018                        if self.moreDebug:
1019                            uLogger.debug("FIGI [{}] found in bonds list".format(self._figi))
1020
1021                        break
1022
1023            if not figiJSON:
1024                for item in self.iList["Etfs"].keys():
1025                    if self._figi == self.iList["Etfs"][item]["figi"]:
1026                        figiJSON = self.iList["Etfs"][item]
1027
1028                        if self.moreDebug:
1029                            uLogger.debug("FIGI [{}] found in etfs list".format(self._figi))
1030
1031                        break
1032
1033            if not figiJSON:
1034                for item in self.iList["Futures"].keys():
1035                    if self._figi == self.iList["Futures"][item]["figi"]:
1036                        figiJSON = self.iList["Futures"][item]
1037
1038                        if self.moreDebug:
1039                            uLogger.debug("FIGI [{}] found in futures list".format(self._figi))
1040
1041                        break
1042
1043        if figiJSON:
1044            self._figi = figiJSON["figi"]
1045            self._ticker = figiJSON["ticker"]
1046
1047            if requestPrice:
1048                figiJSON["currentPrice"] = self.GetCurrentPrices(show=False)
1049
1050                if figiJSON["currentPrice"]["closePrice"] is not None and figiJSON["currentPrice"]["closePrice"] != 0 and figiJSON["currentPrice"]["lastPrice"] is not None:
1051                    figiJSON["currentPrice"]["changes"] = 100 * (figiJSON["currentPrice"]["lastPrice"] - figiJSON["currentPrice"]["closePrice"]) / figiJSON["currentPrice"]["closePrice"]
1052
1053                else:
1054                    figiJSON["currentPrice"]["changes"] = 0
1055
1056            if show:
1057                self.ShowInstrumentInfo(iJSON=figiJSON, show=True)  # print info as Markdown text
1058
1059        else:
1060            if show:
1061                uLogger.warning("FIGI [{}] not found in available broker instrument's list!".format(self._figi))
1062
1063        return figiJSON
1064
1065    def GetCurrentPrices(self, show: bool = True) -> dict:
1066        """
1067        Get and show Depth of Market with current prices of the instrument as dictionary. Result example with `depth` 5:
1068        `{"buy": [{"price": 1243.8, "quantity": 193},
1069                  {"price": 1244.0, "quantity": 168},
1070                  {"price": 1244.8, "quantity": 5},
1071                  {"price": 1245.0, "quantity": 61},
1072                  {"price": 1245.4, "quantity": 60}],
1073          "sell": [{"price": 1243.6, "quantity": 8},
1074                   {"price": 1242.6, "quantity": 10},
1075                   {"price": 1242.4, "quantity": 18},
1076                   {"price": 1242.2, "quantity": 50},
1077                   {"price": 1242.0, "quantity": 113}],
1078          "limitUp": 1619.0, "limitDown": 903.4, "lastPrice": 1243.8, "closePrice": 1263.0}`, where parameters mean:
1079        - buy: list of dicts with Sellers prices, see also: https://tinkoff.github.io/investAPI/marketdata/#order
1080        - sell: list of dicts with Buyers prices,
1081            - price: price of 1 instrument (to get the cost of the lot, you need to multiply it by the lot of size of the instrument),
1082            - quantity: volume value by current price in lots,
1083        - limitUp: current trade session limit price, maximum,
1084        - limitDown: current trade session limit price, minimum,
1085        - lastPrice: last deal price of the instrument,
1086        - closePrice: previous trade session close price of the instrument.
1087
1088        See also: `SearchByTicker()` and `SearchByFIGI()`.
1089        REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetOrderBook
1090        Response fields: https://tinkoff.github.io/investAPI/marketdata/#getorderbookresponse
1091
1092        :param show: if `True` then print DOM to log and console.
1093        :return: orders book dict with lists of current buy and sell prices: `{"buy": [{"price": x1, "quantity": y1, ...}], "sell": [....]}`.
1094                 If an error occurred then returns an empty record:
1095                 `{"buy": [], "sell": [], "limitUp": None, "limitDown": None, "lastPrice": None, "closePrice": None}`.
1096        """
1097        prices = {"buy": [], "sell": [], "limitUp": 0, "limitDown": 0, "lastPrice": 0, "closePrice": 0}
1098
1099        if self.depth < 1:
1100            uLogger.error("Depth of Market (DOM) must be >=1!")
1101            raise Exception("Incorrect value")
1102
1103        if not (self._ticker or self._figi):
1104            uLogger.error("self._ticker or self._figi variables must be defined!")
1105            raise Exception("Ticker or FIGI required")
1106
1107        if self._ticker and not self._figi:
1108            instrumentByTicker = self.SearchByTicker(requestPrice=False)  # WARNING! requestPrice=False to avoid recursion!
1109            self._figi = instrumentByTicker["figi"] if instrumentByTicker else ""
1110
1111        if not self._ticker and self._figi:
1112            instrumentByFigi = self.SearchByFIGI(requestPrice=False)  # WARNING! requestPrice=False to avoid recursion!
1113            self._ticker = instrumentByFigi["ticker"] if instrumentByFigi else ""
1114
1115        if not self._figi:
1116            uLogger.error("FIGI is not defined!")
1117            raise Exception("Ticker or FIGI required")
1118
1119        else:
1120            uLogger.debug("Requesting current prices: ticker [{}], FIGI [{}]. Wait, please...".format(self._ticker, self._figi))
1121
1122            # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetOrderBook
1123            priceURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetOrderBook"
1124            self.body = str({"figi": self._figi, "depth": self.depth})
1125            pricesResponse = self.SendAPIRequest(priceURL, reqType="POST")  # Response fields: https://tinkoff.github.io/investAPI/marketdata/#getorderbookresponse
1126
1127            if pricesResponse and not ("code" in pricesResponse.keys() or "message" in pricesResponse.keys() or "description" in pricesResponse.keys()):
1128                # list of dicts with sellers orders:
1129                prices["buy"] = [{"price": round(NanoToFloat(item["price"]["units"], item["price"]["nano"]), 6), "quantity": int(item["quantity"])} for item in pricesResponse["asks"]]
1130
1131                # list of dicts with buyers orders:
1132                prices["sell"] = [{"price": round(NanoToFloat(item["price"]["units"], item["price"]["nano"]), 6), "quantity": int(item["quantity"])} for item in pricesResponse["bids"]]
1133
1134                # max price of instrument at this time:
1135                prices["limitUp"] = round(NanoToFloat(pricesResponse["limitUp"]["units"], pricesResponse["limitUp"]["nano"]), 6) if "limitUp" in pricesResponse.keys() else None
1136
1137                # min price of instrument at this time:
1138                prices["limitDown"] = round(NanoToFloat(pricesResponse["limitDown"]["units"], pricesResponse["limitDown"]["nano"]), 6) if "limitDown" in pricesResponse.keys() else None
1139
1140                # last price of deal with instrument:
1141                prices["lastPrice"] = round(NanoToFloat(pricesResponse["lastPrice"]["units"], pricesResponse["lastPrice"]["nano"]), 6) if "lastPrice" in pricesResponse.keys() else 0
1142
1143                # last close price of instrument:
1144                prices["closePrice"] = round(NanoToFloat(pricesResponse["closePrice"]["units"], pricesResponse["closePrice"]["nano"]), 6) if "closePrice" in pricesResponse.keys() else 0
1145
1146            else:
1147                uLogger.warning("Server return an empty or error response! See full log. Instrument: ticker [{}], FIGI [{}]".format(self._ticker, self._figi))
1148                uLogger.debug("Server response: {}".format(pricesResponse))
1149
1150            if show:
1151                if prices["buy"] or prices["sell"]:
1152                    info = [
1153                        "Orders book actual at [{}] (UTC)\nTicker: [{}], FIGI: [{}], Depth of Market: [{}]\n".format(
1154                            datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
1155                            self._ticker,
1156                            self._figi,
1157                            self.depth,
1158                        ),
1159                        "-" * 60, "\n",
1160                        "             Orders of Buyers | Orders of Sellers\n",
1161                        "-" * 60, "\n",
1162                        "        Sell prices (volumes) | Buy prices (volumes)\n",
1163                        "-" * 60, "\n",
1164                    ]
1165
1166                    if not prices["buy"]:
1167                        info.append("                              | No orders!\n")
1168                        sumBuy = 0
1169
1170                    else:
1171                        sumBuy = sum([x["quantity"] for x in prices["buy"]])
1172                        maxMinSorted = sorted(prices["buy"], key=lambda k: k["price"], reverse=True)
1173                        for item in maxMinSorted:
1174                            info.append("                              | {} ({})\n".format(item["price"], item["quantity"]))
1175
1176                    if not prices["sell"]:
1177                        info.append("No orders!                    |\n")
1178                        sumSell = 0
1179
1180                    else:
1181                        sumSell = sum([x["quantity"] for x in prices["sell"]])
1182                        for item in prices["sell"]:
1183                            info.append("{:>29} |\n".format("{} ({})".format(item["price"], item["quantity"])))
1184
1185                    info.extend([
1186                        "-" * 60, "\n",
1187                        "{:>29} | {}\n".format("Total sell: {}".format(sumSell), "Total buy: {}".format(sumBuy)),
1188                        "-" * 60, "\n",
1189                    ])
1190
1191                    infoText = "".join(info)
1192
1193                    uLogger.info("Current prices in order book:\n\n{}".format(infoText))
1194
1195                else:
1196                    uLogger.warning("Orders book is empty at this time! Instrument: ticker [{}], FIGI [{}]".format(self._ticker, self._figi))
1197
1198        return prices
1199
1200    def ShowInstrumentsInfo(self, show: bool = True) -> str:
1201        """
1202        This method get and show information about all available broker instruments for current user account.
1203        If `instrumentsFile` string is not empty then also save information to this file.
1204
1205        :param show: if `True` then print results to console, if `False` — print only to file.
1206        :return: multi-lines string with all available broker instruments
1207        """
1208        if not self.iList:
1209            self.iList = self.Listing()
1210
1211        info = [
1212            "# All available instruments from Tinkoff Broker server for current user token\n\n",
1213            "* **Actual on date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
1214        ]
1215
1216        # add instruments count by type:
1217        for iType in self.iList.keys():
1218            info.append("* **{}:** [{}]\n".format(iType, len(self.iList[iType])))
1219
1220        headerLine = "| Ticker       | Full name                                                 | FIGI         | Cur | Lot     | Step       |\n"
1221        splitLine = "|--------------|-----------------------------------------------------------|--------------|-----|---------|------------|\n"
1222
1223        # generating info tables with all instruments by type:
1224        for iType in self.iList.keys():
1225            info.extend(["\n\n## {} available. Total: [{}]\n\n".format(iType, len(self.iList[iType])), headerLine, splitLine])
1226
1227            for instrument in self.iList[iType].keys():
1228                iName = self.iList[iType][instrument]["name"]  # instrument's name
1229                if len(iName) > 57:
1230                    iName = "{}...".format(iName[:54])  # right trim for a long string
1231
1232                info.append("| {:<12} | {:<57} | {:<12} | {:<3} | {:<7} | {:<10} |\n".format(
1233                    self.iList[iType][instrument]["ticker"],
1234                    iName,
1235                    self.iList[iType][instrument]["figi"],
1236                    self.iList[iType][instrument]["currency"],
1237                    self.iList[iType][instrument]["lot"],
1238                    "{:.10f}".format(self.iList[iType][instrument]["step"]).rstrip("0").rstrip(".") if self.iList[iType][instrument]["step"] > 0 else 0,
1239                ))
1240
1241        infoText = "".join(info)
1242
1243        if show:
1244            uLogger.info(infoText)
1245
1246        if self.instrumentsFile:
1247            with open(self.instrumentsFile, "w", encoding="UTF-8") as fH:
1248                fH.write(infoText)
1249
1250            uLogger.info("All available instruments are saved to file: [{}]".format(os.path.abspath(self.instrumentsFile)))
1251
1252            if self.useHTMLReports:
1253                htmlFilePath = self.instrumentsFile.replace(".md", ".html") if self.instrumentsFile.endswith(".md") else self.instrumentsFile + ".html"
1254                with open(htmlFilePath, "w", encoding="UTF-8") as fH:
1255                    fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="List of instruments", commonCSS=COMMON_CSS, markdown=infoText))
1256
1257                uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
1258
1259        return infoText
1260
1261    def SearchInstruments(self, pattern: str, show: bool = True) -> dict:
1262        """
1263        This method search and show information about instruments by part of its ticker, FIGI or name.
1264        If `searchResultsFile` string is not empty then also save information to this file.
1265
1266        :param pattern: string with part of ticker, FIGI or instrument's name.
1267        :param show: if `True` then print results to console, if `False` — return list of result only.
1268        :return: list of dictionaries with all found instruments.
1269        """
1270        if not self.iList:
1271            self.iList = self.Listing()
1272
1273        searchResults = {iType: {} for iType in self.iList}  # same as iList but will contain only filtered instruments
1274        compiledPattern = re.compile(pattern, re.IGNORECASE)
1275
1276        for iType in self.iList:
1277            for instrument in self.iList[iType].values():
1278                searchResult = compiledPattern.search(" ".join(
1279                    [instrument["ticker"], instrument["figi"], instrument["name"]]
1280                ))
1281
1282                if searchResult:
1283                    searchResults[iType][instrument["ticker"]] = instrument
1284
1285        resultsLen = sum([len(searchResults[iType]) for iType in searchResults])
1286        info = [
1287            "# Search results\n\n",
1288            "* **Actual on date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
1289            "* **Search pattern:** [{}]\n".format(pattern),
1290            "* **Found instruments:** [{}]\n\n".format(resultsLen),
1291            '**Note:** you can view info about found instruments with key "--info", e.g.: "tksbrokerapi -t TICKER --info" or "tksbrokerapi -f FIGI --info".\n'
1292        ]
1293        infoShort = info[:]
1294
1295        headerLine = "| Type       | Ticker       | Full name                                                      | FIGI         |\n"
1296        splitLine = "|------------|--------------|----------------------------------------------------------------|--------------|\n"
1297        skippedLine = "| ...        | ...          | ...                                                            | ...          |\n"
1298
1299        if resultsLen == 0:
1300            info.append("\nNo results\n")
1301            infoShort.append("\nNo results\n")
1302            uLogger.warning("No results. Try changing your search pattern.")
1303
1304        else:
1305            for iType in searchResults:
1306                iTypeValuesCount = len(searchResults[iType].values())
1307                if iTypeValuesCount > 0:
1308                    info.extend(["\n## {}: [{}]\n\n".format(iType, iTypeValuesCount), headerLine, splitLine])
1309                    infoShort.extend(["\n### {}: [{}]\n\n".format(iType, iTypeValuesCount), headerLine, splitLine])
1310
1311                    for instrument in searchResults[iType].values():
1312                        info.append("| {:<10} | {:<12} | {:<63}| {:<13}|\n".format(
1313                            instrument["type"],
1314                            instrument["ticker"],
1315                            "{}...".format(instrument["name"][:60]) if len(instrument["name"]) > 63 else instrument["name"],  # right trim for a long string
1316                            instrument["figi"],
1317                        ))
1318
1319                    if iTypeValuesCount <= 5:
1320                        infoShort.extend(info[-iTypeValuesCount:])
1321
1322                    else:
1323                        infoShort.extend(info[-5:])
1324                        infoShort.append(skippedLine)
1325
1326        infoText = "".join(info)
1327        infoTextShort = "".join(infoShort)
1328
1329        if show:
1330            uLogger.info(infoTextShort)
1331            uLogger.info("You can view info about found instruments with key `--info`, e.g.: `tksbrokerapi -t IBM --info` or `tksbrokerapi -f BBG000BLNNH6 --info`")
1332
1333        if self.searchResultsFile:
1334            with open(self.searchResultsFile, "w", encoding="UTF-8") as fH:
1335                fH.write(infoText)
1336
1337            uLogger.info("Full search results were saved to file: [{}]".format(os.path.abspath(self.searchResultsFile)))
1338
1339            if self.useHTMLReports:
1340                htmlFilePath = self.searchResultsFile.replace(".md", ".html") if self.searchResultsFile.endswith(".md") else self.searchResultsFile + ".html"
1341                with open(htmlFilePath, "w", encoding="UTF-8") as fH:
1342                    fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Search results", commonCSS=COMMON_CSS, markdown=infoText))
1343
1344                uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
1345
1346        return searchResults
1347
1348    def GetUniqueFIGIs(self, instruments: list[str]) -> list:
1349        """
1350        Creating list with unique instrument FIGIs from input list of tickers (priority) or FIGIs.
1351
1352        :param instruments: list of strings with tickers or FIGIs.
1353        :return: list with unique instrument FIGIs only.
1354        """
1355        requestedInstruments = []
1356        for iName in instruments:
1357            if iName not in self.aliases.keys():
1358                if iName not in requestedInstruments:
1359                    requestedInstruments.append(iName)
1360
1361            else:
1362                if iName not in requestedInstruments:
1363                    if self.aliases[iName] not in requestedInstruments:
1364                        requestedInstruments.append(self.aliases[iName])
1365
1366        uLogger.debug("Requested instruments without duplicates of tickers or FIGIs: {}".format(requestedInstruments))
1367
1368        onlyUniqueFIGIs = []
1369        for iName in requestedInstruments:
1370            if iName in TKS_TICKERS_OR_FIGI_EXCLUDED:
1371                continue
1372
1373            self._ticker = iName
1374            iData = self.SearchByTicker(requestPrice=False)  # trying to find instrument by ticker
1375
1376            if not iData:
1377                self._ticker = ""
1378                self._figi = iName
1379
1380                iData = self.SearchByFIGI(requestPrice=False)  # trying to find instrument by FIGI
1381
1382                if not iData:
1383                    self._figi = ""
1384                    uLogger.warning("Instrument [{}] not in list of available instruments for current token!".format(iName))
1385
1386            if iData and iData["figi"] not in onlyUniqueFIGIs:
1387                onlyUniqueFIGIs.append(iData["figi"])
1388
1389        uLogger.debug("Unique list of FIGIs: {}".format(onlyUniqueFIGIs))
1390
1391        return onlyUniqueFIGIs
1392
1393    def GetListOfPrices(self, instruments: list[str], show: bool = False) -> list[dict]:
1394        """
1395        This method get, maybe show and return prices of list of instruments. WARNING! This is potential long operation!
1396
1397        See limits: https://tinkoff.github.io/investAPI/limits/
1398
1399        If `pricesFile` string is not empty then also save information to this file.
1400
1401        :param instruments: list of strings with tickers or FIGIs.
1402        :param show: if `True` then prints prices to console, if `False` — prints only to file `pricesFile`.
1403        :return: list of instruments looks like `[{some ticker info, "currentPrice": {current prices}}, {...}, ...]`.
1404                 One item is dict returned by `SearchByTicker()` or `SearchByFIGI()` methods.
1405        """
1406        if instruments is None or not instruments:
1407            uLogger.error("You must define some of tickers or FIGIs to request it's actual prices!")
1408            raise Exception("Ticker or FIGI required")
1409
1410        onlyUniqueFIGIs = self.GetUniqueFIGIs(instruments)
1411
1412        uLogger.debug("Requesting current prices from Tinkoff Broker server...")
1413
1414        iList = []  # trying to get info and current prices about all unique instruments:
1415        for self._figi in onlyUniqueFIGIs:
1416            iData = self.SearchByFIGI(requestPrice=True)
1417            iList.append(iData)
1418
1419        self.ShowListOfPrices(iList, show)
1420
1421        return iList
1422
1423    def ShowListOfPrices(self, iList: list, show: bool = True) -> str:
1424        """
1425        Show table contains current prices of given instruments.
1426
1427        :param iList: list of instruments looks like `[{some ticker info, "currentPrice": {current prices}}, {...}, ...]`.
1428                      One item is dict returned by `SearchByTicker(requestPrice=True)` or by `SearchByFIGI(requestPrice=True)` methods.
1429        :param show: if `True` then prints prices to console, if `False` — prints only to file `pricesFile`.
1430        :return: multilines text in Markdown format as a table contains current prices.
1431        """
1432        infoText = ""
1433
1434        if show or self.pricesFile:
1435            info = [
1436                "# Current prices\n\n* **Actual on date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime("%Y-%m-%d %H:%M")),
1437                "| Ticker       | FIGI         | Type       | Prev. close | Last price  | Chg. %   | Day limits min/max  | Actual sell / buy   | Curr. |\n",
1438                "|--------------|--------------|------------|-------------|-------------|----------|---------------------|---------------------|-------|\n",
1439            ]
1440
1441            for item in iList:
1442                info.append("| {:<12} | {:<12} | {:<10} | {:>11} | {:>11} | {:>7}% | {:>19} | {:>19} | {:<5} |\n".format(
1443                    item["ticker"],
1444                    item["figi"],
1445                    item["type"],
1446                    "{:.2f}".format(float(item["currentPrice"]["closePrice"])),
1447                    "{:.2f}".format(float(item["currentPrice"]["lastPrice"])),
1448                    "{}{:.2f}".format("+" if item["currentPrice"]["changes"] > 0 else "", float(item["currentPrice"]["changes"])),
1449                    "{} / {}".format(
1450                        item["currentPrice"]["limitDown"] if item["currentPrice"]["limitDown"] is not None else "N/A",
1451                        item["currentPrice"]["limitUp"] if item["currentPrice"]["limitUp"] is not None else "N/A",
1452                    ),
1453                    "{} / {}".format(
1454                        item["currentPrice"]["sell"][0]["price"] if item["currentPrice"]["sell"] else "N/A",
1455                        item["currentPrice"]["buy"][0]["price"] if item["currentPrice"]["buy"] else "N/A",
1456                    ),
1457                    item["currency"],
1458                ))
1459
1460            infoText = "".join(info)
1461
1462            if show:
1463                uLogger.info("Only instruments with unique FIGIs are shown:\n{}".format(infoText))
1464
1465            if self.pricesFile:
1466                with open(self.pricesFile, "w", encoding="UTF-8") as fH:
1467                    fH.write(infoText)
1468
1469                uLogger.info("Price list for all instruments saved to file: [{}]".format(os.path.abspath(self.pricesFile)))
1470
1471                if self.useHTMLReports:
1472                    htmlFilePath = self.pricesFile.replace(".md", ".html") if self.pricesFile.endswith(".md") else self.pricesFile + ".html"
1473                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
1474                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Current prices", commonCSS=COMMON_CSS, markdown=infoText))
1475
1476                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
1477
1478        return infoText
1479
1480    def RequestTradingStatus(self) -> dict:
1481        """
1482        Requesting trading status for the instrument defined by `figi` variable.
1483
1484        REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetTradingStatus
1485
1486        Documentation: https://tinkoff.github.io/investAPI/marketdata/#gettradingstatusrequest
1487
1488        :return: dictionary with trading status attributes. Response example:
1489                 `{"figi": "TCS00A103X66", "tradingStatus": "SECURITY_TRADING_STATUS_NOT_AVAILABLE_FOR_TRADING",
1490                  "limitOrderAvailableFlag": false, "marketOrderAvailableFlag": false, "apiTradeAvailableFlag": true}`
1491        """
1492        if self._figi is None or not self._figi:
1493            uLogger.error("Variable `figi` must be defined for using this method!")
1494            raise Exception("FIGI required")
1495
1496        uLogger.debug("Requesting current trading status, FIGI: [{}]. Wait, please...".format(self._figi))
1497
1498        self.body = str({"figi": self._figi, "instrumentId": self._figi})
1499        tradingStatusURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetTradingStatus"
1500        tradingStatus = self.SendAPIRequest(tradingStatusURL, reqType="POST")
1501
1502        if self.moreDebug:
1503            uLogger.debug("Records about current trading status successfully received")
1504
1505        return tradingStatus
1506
1507    def RequestPortfolio(self) -> dict:
1508        """
1509        Requesting actual user's portfolio for current `accountId`.
1510
1511        REST API for user portfolio: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetPortfolio
1512
1513        Documentation: https://tinkoff.github.io/investAPI/operations/#portfoliorequest
1514
1515        :return: dictionary with user's portfolio.
1516        """
1517        if self.accountId is None or not self.accountId:
1518            uLogger.error("Variable `accountId` must be defined for using this method!")
1519            raise Exception("Account ID required")
1520
1521        uLogger.debug("Requesting current actual user's portfolio. Wait, please...")
1522
1523        self.body = str({"accountId": self.accountId})
1524        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetPortfolio"
1525        rawPortfolio = self.SendAPIRequest(portfolioURL, reqType="POST")
1526
1527        if self.moreDebug:
1528            uLogger.debug("Records about user's portfolio successfully received")
1529
1530        return rawPortfolio
1531
1532    def RequestPositions(self) -> dict:
1533        """
1534        Requesting open positions by currencies and instruments for current `accountId`.
1535
1536        REST API for open positions: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetPositions
1537
1538        Documentation: https://tinkoff.github.io/investAPI/operations/#positionsrequest
1539
1540        :return: dictionary with open positions by instruments.
1541        """
1542        if self.accountId is None or not self.accountId:
1543            uLogger.error("Variable `accountId` must be defined for using this method!")
1544            raise Exception("Account ID required")
1545
1546        uLogger.debug("Requesting current open positions in currencies and instruments. Wait, please...")
1547
1548        self.body = str({"accountId": self.accountId})
1549        positionsURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetPositions"
1550        rawPositions = self.SendAPIRequest(positionsURL, reqType="POST")
1551
1552        if self.moreDebug:
1553            uLogger.debug("Records about current open positions successfully received")
1554
1555        return rawPositions
1556
1557    def RequestPendingOrders(self) -> list:
1558        """
1559        Requesting current actual pending limit orders for current `accountId`.
1560
1561        REST API for pending (market) orders: https://tinkoff.github.io/investAPI/swagger-ui/#/OrdersService/OrdersService_GetOrders
1562
1563        Documentation: https://tinkoff.github.io/investAPI/orders/#getordersrequest
1564
1565        :return: list of dictionaries with pending limit orders.
1566        """
1567        if self.accountId is None or not self.accountId:
1568            uLogger.error("Variable `accountId` must be defined for using this method!")
1569            raise Exception("Account ID required")
1570
1571        uLogger.debug("Requesting current actual pending limit orders. Wait, please...")
1572
1573        self.body = str({"accountId": self.accountId})
1574        ordersURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/GetOrders"
1575        rawResponse = self.SendAPIRequest(ordersURL, reqType="POST")
1576
1577        if "orders" in rawResponse.keys():
1578            rawOrders = rawResponse["orders"]
1579            uLogger.debug("[{}] records about pending limit orders received".format(len(rawOrders)))
1580
1581        else:
1582            rawOrders = []
1583            uLogger.debug("No pending limit orders returned! rawResponse = {}".format(rawResponse))
1584
1585        return rawOrders
1586
1587    def RequestStopOrders(self) -> list:
1588        """
1589        Requesting current actual stop orders for current `accountId`.
1590
1591        REST API for opened stop-orders: https://tinkoff.github.io/investAPI/swagger-ui/#/StopOrdersService/StopOrdersService_GetStopOrders
1592
1593        Documentation: https://tinkoff.github.io/investAPI/stoporders/#getstopordersrequest
1594
1595        :return: list of dictionaries with stop orders.
1596        """
1597        if self.accountId is None or not self.accountId:
1598            uLogger.error("Variable `accountId` must be defined for using this method!")
1599            raise Exception("Account ID required")
1600
1601        uLogger.debug("Requesting current actual stop orders. Wait, please...")
1602
1603        self.body = str({"accountId": self.accountId})
1604        stopOrdersURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/GetStopOrders"
1605        rawResponse = self.SendAPIRequest(stopOrdersURL, reqType="POST")
1606
1607        if "stopOrders" in rawResponse.keys():
1608            rawStopOrders = rawResponse["stopOrders"]
1609            uLogger.debug("[{}] records about stop orders received".format(len(rawStopOrders)))
1610
1611        else:
1612            rawStopOrders = []
1613            uLogger.debug("No stop orders returned! rawResponse = {}".format(rawResponse))
1614
1615        return rawStopOrders
1616
1617    def Overview(self, show: bool = False, details: str = "full") -> dict:
1618        """
1619        Get portfolio: all open positions, orders and some statistics for current `accountId`.
1620        If `overviewFile`, `overviewDigestFile`, `overviewPositionsFile`, `overviewOrdersFile`, `overviewAnalyticsFile`
1621        and `overviewBondsCalendarFile` are defined then also save information to file.
1622
1623        WARNING! It is not recommended to run this method too many times in a loop! The server receives
1624        many requests about the state of the portfolio, and then, based on the received data, a large number
1625        of calculation and statistics are collected.
1626
1627        :param show: if `False` then only dictionary returns, if `True` then show more debug information.
1628        :param details: how detailed should the information be?
1629        - `full` — shows full available information about portfolio status (by default),
1630        - `positions` — shows only open positions,
1631        - `orders` — shows only sections of open limits and stop orders.
1632        - `digest` — show a short digest of the portfolio status,
1633        - `analytics` — shows only the analytics section and the distribution of the portfolio by various categories,
1634        - `calendar` — shows only the bonds calendar section (if these present in portfolio),
1635        :return: dictionary with client's raw portfolio and some statistics.
1636        """
1637        if self.accountId is None or not self.accountId:
1638            uLogger.error("Variable `accountId` must be defined for using this method!")
1639            raise Exception("Account ID required")
1640
1641        view = {
1642            "raw": {  # --- raw portfolio responses from broker with user portfolio data:
1643                "headers": {},  # list of dictionaries, response headers without "positions" section
1644                "Currencies": [],  # list of dictionaries, open trades with currencies from "positions" section
1645                "Shares": [],  # list of dictionaries, open trades with shares from "positions" section
1646                "Bonds": [],  # list of dictionaries, open trades with bonds from "positions" section
1647                "Etfs": [],  # list of dictionaries, open trades with etfs from "positions" section
1648                "Futures": [],  # list of dictionaries, open trades with futures from "positions" section
1649                "positions": {},  # raw response from broker: dictionary with current available or blocked currencies and instruments for client
1650                "orders": [],  # raw response from broker: list of dictionaries with all pending (market) orders
1651                "stopOrders": [],  # raw response from broker: list of dictionaries with all stop orders
1652                "currenciesCurrentPrices": {"rub": {"name": "Российский рубль", "currentPrice": 1.}},  # dict with prices of all currencies in RUB
1653            },
1654            "stat": {  # --- some statistics calculated using "raw" sections:
1655                "portfolioCostRUB": 0.,  # portfolio cost in RUB (Russian Rouble)
1656                "availableRUB": 0.,  # available rubles (without other currencies)
1657                "blockedRUB": 0.,  # blocked sum in Russian Rouble
1658                "totalChangesRUB": 0.,  # changes for all open trades in RUB
1659                "totalChangesPercentRUB": 0.,  # changes for all open trades in percents
1660                "allCurrenciesCostRUB": 0.,  # costs of all currencies (include rubles) in RUB
1661                "sharesCostRUB": 0.,  # costs of all shares in RUB
1662                "bondsCostRUB": 0.,  # costs of all bonds in RUB
1663                "etfsCostRUB": 0.,  # costs of all etfs in RUB
1664                "futuresCostRUB": 0.,  # costs of all futures in RUB
1665                "Currencies": [],  # list of dictionaries of all currencies statistics
1666                "Shares": [],  # list of dictionaries of all shares statistics
1667                "Bonds": [],  # list of dictionaries of all bonds statistics
1668                "Etfs": [],  # list of dictionaries of all etfs statistics
1669                "Futures": [],  # list of dictionaries of all futures statistics
1670                "orders": [],  # list of dictionaries of all pending (market) orders and it's parameters
1671                "stopOrders": [],  # list of dictionaries of all stop orders and it's parameters
1672                "blockedCurrencies": {},  # dict with blocked instruments and currencies, e.g. {"rub": 1291.87, "usd": 6.21}
1673                "blockedInstruments": {},  # dict with blocked  by FIGI, e.g. {}
1674                "funds": {},  # dict with free funds for trading (total - blocked), by all currencies, e.g. {"rub": {"total": 10000.99, "totalCostRUB": 10000.99, "free": 1234.56, "freeCostRUB": 1234.56}, "usd": {"total": 250.55, "totalCostRUB": 15375.80, "free": 125.05, "freeCostRUB": 7687.50}}
1675            },
1676            "analytics": {  # --- some analytics of portfolio:
1677                "distrByAssets": {},  # portfolio distribution by assets
1678                "distrByCompanies": {},  # portfolio distribution by companies
1679                "distrBySectors": {},  # portfolio distribution by sectors
1680                "distrByCurrencies": {},  # portfolio distribution by currencies
1681                "distrByCountries": {},  # portfolio distribution by countries
1682                "bondsCalendar": None,  # bonds payment calendar as Pandas DataFrame (if these present in portfolio)
1683            }
1684        }
1685
1686        details = details.lower()
1687        availableDetails = ["full", "positions", "orders", "analytics", "calendar", "digest"]
1688        if details not in availableDetails:
1689            details = "full"
1690            uLogger.debug("Requested incorrect details! The `details` must be one of this strings: {}. Details parameter set to `full` be default.".format(availableDetails))
1691
1692        uLogger.debug("Requesting portfolio of a client. Wait, please...")
1693
1694        portfolioResponse = self.RequestPortfolio()  # current user's portfolio (dict)
1695        view["raw"]["positions"] = self.RequestPositions()  # current open positions by instruments (dict)
1696        view["raw"]["orders"] = self.RequestPendingOrders()  # current actual pending limit orders (list)
1697        view["raw"]["stopOrders"] = self.RequestStopOrders()  # current actual stop orders (list)
1698
1699        # save response headers without "positions" section:
1700        for key in portfolioResponse.keys():
1701            if key != "positions":
1702                view["raw"]["headers"][key] = portfolioResponse[key]
1703
1704            else:
1705                continue
1706
1707        # Re-sorting and separating given raw instruments and currencies by type: https://tinkoff.github.io/investAPI/operations/#operation
1708        # Type of instrument must be only one of supported types in TKS_INSTRUMENTS
1709        for item in portfolioResponse["positions"]:
1710            if item["instrumentType"] == "currency":
1711                self._figi = item["figi"]
1712                if not self._figi and item["ticker"]:
1713                    self._ticker = item["ticker"]
1714                    self._figi = self.SearchByTicker()["figi"]  # Get FIGI to avoid warnings
1715
1716                curr = self.SearchByFIGI(requestPrice=False)
1717
1718                # current price of currency in RUB:
1719                view["raw"]["currenciesCurrentPrices"][curr["nominal"]["currency"]] = {
1720                    "name": curr["name"],
1721                    "currentPrice": NanoToFloat(
1722                        item["currentPrice"]["units"],
1723                        item["currentPrice"]["nano"]
1724                    ),
1725                }
1726
1727                view["raw"]["Currencies"].append(item)
1728
1729            elif item["instrumentType"] == "share":
1730                view["raw"]["Shares"].append(item)
1731
1732            elif item["instrumentType"] == "bond":
1733                view["raw"]["Bonds"].append(item)
1734
1735            elif item["instrumentType"] == "etf":
1736                view["raw"]["Etfs"].append(item)
1737
1738            elif item["instrumentType"] == "futures":
1739                view["raw"]["Futures"].append(item)
1740
1741            else:
1742                continue
1743
1744        # how many volume of currencies (by ISO currency name) are blocked:
1745        for item in view["raw"]["positions"]["blocked"]:
1746            blocked = NanoToFloat(item["units"], item["nano"])
1747            if blocked > 0:
1748                view["stat"]["blockedCurrencies"][item["currency"]] = blocked
1749
1750        # how many volume of instruments (by FIGI) are blocked:
1751        for item in view["raw"]["positions"]["securities"]:
1752            blocked = int(item["blocked"])
1753            if blocked > 0:
1754                view["stat"]["blockedInstruments"][item["figi"]] = blocked
1755
1756        allBlocked = {**view["stat"]["blockedCurrencies"], **view["stat"]["blockedInstruments"]}
1757
1758        if "rub" in allBlocked.keys():
1759            view["stat"]["blockedRUB"] = allBlocked["rub"]  # blocked rubles
1760
1761        # --- saving current total amount in RUB of all currencies (with ruble), shares, bonds, etfs, futures and currencies:
1762        view["stat"]["allCurrenciesCostRUB"] = NanoToFloat(portfolioResponse["totalAmountCurrencies"]["units"], portfolioResponse["totalAmountCurrencies"]["nano"])
1763        view["stat"]["sharesCostRUB"] = NanoToFloat(portfolioResponse["totalAmountShares"]["units"], portfolioResponse["totalAmountShares"]["nano"])
1764        view["stat"]["bondsCostRUB"] = NanoToFloat(portfolioResponse["totalAmountBonds"]["units"], portfolioResponse["totalAmountBonds"]["nano"])
1765        view["stat"]["etfsCostRUB"] = NanoToFloat(portfolioResponse["totalAmountEtf"]["units"], portfolioResponse["totalAmountEtf"]["nano"])
1766        view["stat"]["futuresCostRUB"] = NanoToFloat(portfolioResponse["totalAmountFutures"]["units"], portfolioResponse["totalAmountFutures"]["nano"])
1767        view["stat"]["portfolioCostRUB"] = sum([
1768            view["stat"]["allCurrenciesCostRUB"],
1769            view["stat"]["sharesCostRUB"],
1770            view["stat"]["bondsCostRUB"],
1771            view["stat"]["etfsCostRUB"],
1772            view["stat"]["futuresCostRUB"],
1773        ])
1774
1775        # --- calculating some portfolio statistics:
1776        byComp = {}  # distribution by companies
1777        bySect = {}  # distribution by sectors
1778        byCurr = {}  # distribution by currencies (include RUB)
1779        unknownCountryName = "All other countries"  # default name for instruments without "countryOfRisk" and "countryOfRiskName"
1780        byCountry = {unknownCountryName: {"cost": 0, "percent": 0.}}  # distribution by countries (currencies are included in their countries)
1781
1782        for item in portfolioResponse["positions"]:
1783            self._figi = item["figi"]
1784            if not self._figi and item["ticker"]:
1785                self._ticker = item["ticker"]
1786                self._figi = self.SearchByTicker()["figi"]  # Get FIGI to avoid warnings
1787
1788            instrument = self.SearchByFIGI(requestPrice=False)  # full raw info about instrument by FIGI
1789
1790            if instrument:
1791                if item["instrumentType"] == "currency" and instrument["nominal"]["currency"] in allBlocked.keys():
1792                    blocked = allBlocked[instrument["nominal"]["currency"]]  # blocked volume of currency
1793
1794                elif item["instrumentType"] != "currency" and item["figi"] in allBlocked.keys():
1795                    blocked = allBlocked[item["figi"]]  # blocked volume of other instruments
1796
1797                else:
1798                    blocked = 0
1799
1800                volume = NanoToFloat(item["quantity"]["units"], item["quantity"]["nano"])  # available volume of instrument
1801                lots = NanoToFloat(item["quantityLots"]["units"], item["quantityLots"]["nano"])  # available volume in lots of instrument
1802                direction = "Long" if lots >= 0 else "Short"  # direction of an instrument's position: short or long
1803                curPrice = NanoToFloat(item["currentPrice"]["units"], item["currentPrice"]["nano"])  # current instrument's price
1804                average = NanoToFloat(item["averagePositionPriceFifo"]["units"], item["averagePositionPriceFifo"]["nano"])  # current average position price
1805                profit = NanoToFloat(item["expectedYield"]["units"], item["expectedYield"]["nano"])  # expected profit at current moment
1806                currency = instrument["currency"] if (item["instrumentType"] == "share" or item["instrumentType"] == "etf" or item["instrumentType"] == "future") else instrument["nominal"]["currency"]  # currency name rub, usd, eur etc.
1807                cost = curPrice if "currentNkd" not in item.keys() else (curPrice + NanoToFloat(item["currentNkd"]["units"], item["currentNkd"]["nano"])) * volume  # current cost of all volume of instrument in basic asset
1808                baseCurrencyName = item["currentPrice"]["currency"]  # name of base currency (rub)
1809                countryName = "[{}] {}".format(instrument["countryOfRisk"], instrument["countryOfRiskName"]) if "countryOfRisk" in instrument.keys() and "countryOfRiskName" in instrument.keys() and instrument["countryOfRisk"] and instrument["countryOfRiskName"] else unknownCountryName
1810                costRUB = cost if item["instrumentType"] == "currency" else cost * view["raw"]["currenciesCurrentPrices"][currency]["currentPrice"]  # cost in rubles
1811                percentCostRUB = 100 * costRUB / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.  # instrument's part in percent of full portfolio cost
1812
1813                statData = {
1814                    "figi": item["figi"],  # FIGI from REST API "GetPortfolio" method
1815                    "ticker": instrument["ticker"],  # ticker by FIGI
1816                    "currency": currency,  # currency name rub, usd, eur etc. for instrument price
1817                    "volume": volume,  # available volume of instrument
1818                    "lots": lots,  # volume in lots of instrument
1819                    "direction": direction,  # direction of an instrument's position: short or long
1820                    "blocked": blocked,  # blocked volume of currency or instrument
1821                    "currentPrice": curPrice,  # current instrument's price in basic asset
1822                    "average": average,  # current average position price
1823                    "cost": cost,  # current cost of all volume of instrument in basic asset
1824                    "baseCurrencyName": baseCurrencyName,  # name of base currency (rub)
1825                    "costRUB": costRUB,  # cost of instrument in ruble
1826                    "percentCostRUB": percentCostRUB,  # instrument's part in percent of full portfolio cost in RUB
1827                    "profit": profit,  # expected profit at current moment
1828                    "percentProfit": 100 * profit / (average * volume) if average != 0 and volume != 0 else 0,  # expected percents of profit at current moment for this instrument
1829                    "sector": instrument["sector"] if "sector" in instrument.keys() and instrument["sector"] else "other",
1830                    "name": instrument["name"] if "name" in instrument.keys() else "",  # human-readable names of instruments
1831                    "isoCurrencyName": instrument["isoCurrencyName"] if "isoCurrencyName" in instrument.keys() else "",  # ISO name for currencies only
1832                    "country": countryName,  # e.g. "[RU] Российская Федерация" or unknownCountryName
1833                    "step": instrument["step"],  # minimum price increment
1834                }
1835
1836                # adding distribution by unique countries:
1837                if statData["country"] not in byCountry.keys():
1838                    byCountry[statData["country"]] = {"cost": costRUB, "percent": percentCostRUB}
1839
1840                else:
1841                    byCountry[statData["country"]]["cost"] += costRUB
1842                    byCountry[statData["country"]]["percent"] += percentCostRUB
1843
1844                if item["instrumentType"] != "currency":
1845                    # adding distribution by unique companies:
1846                    if statData["name"]:
1847                        if statData["name"] not in byComp.keys():
1848                            byComp[statData["name"]] = {"ticker": statData["ticker"], "cost": costRUB, "percent": percentCostRUB}
1849
1850                        else:
1851                            byComp[statData["name"]]["cost"] += costRUB
1852                            byComp[statData["name"]]["percent"] += percentCostRUB
1853
1854                    # adding distribution by unique sectors:
1855                    if statData["sector"] not in bySect.keys():
1856                        bySect[statData["sector"]] = {"cost": costRUB, "percent": percentCostRUB}
1857
1858                    else:
1859                        bySect[statData["sector"]]["cost"] += costRUB
1860                        bySect[statData["sector"]]["percent"] += percentCostRUB
1861
1862                # adding distribution by unique currencies:
1863                if currency not in byCurr.keys():
1864                    byCurr[currency] = {
1865                        "name": view["raw"]["currenciesCurrentPrices"][currency]["name"],
1866                        "cost": costRUB,
1867                        "percent": percentCostRUB
1868                    }
1869
1870                else:
1871                    byCurr[currency]["cost"] += costRUB
1872                    byCurr[currency]["percent"] += percentCostRUB
1873
1874                # saving statistics for every instrument:
1875                if item["instrumentType"] == "currency":
1876                    view["stat"]["Currencies"].append(statData)
1877
1878                    # update dict with free funds for trading (total - blocked) by currencies
1879                    # e.g. {"rub": {"total": 10000.99, "totalCostRUB": 10000.99, "free": 1234.56, "freeCostRUB": 1234.56}, "usd": {"total": 250.55, "totalCostRUB": 15375.80, "free": 125.05, "freeCostRUB": 7687.50}}
1880                    view["stat"]["funds"][currency] = {
1881                        "total": volume,
1882                        "totalCostRUB": costRUB,  # total volume cost in rubles
1883                        "free": volume - blocked,
1884                        "freeCostRUB": costRUB * ((volume - blocked) / volume) if volume > 0 else 0,  # free volume cost in rubles
1885                    }
1886
1887                elif item["instrumentType"] == "share":
1888                    view["stat"]["Shares"].append(statData)
1889
1890                elif item["instrumentType"] == "bond":
1891                    view["stat"]["Bonds"].append(statData)
1892
1893                elif item["instrumentType"] == "etf":
1894                    view["stat"]["Etfs"].append(statData)
1895
1896                elif item["instrumentType"] == "Futures":
1897                    view["stat"]["Futures"].append(statData)
1898
1899                else:
1900                    continue
1901
1902        # total changes in Russian Ruble:
1903        view["stat"]["availableRUB"] = view["stat"]["allCurrenciesCostRUB"] - sum([item["cost"] for item in view["stat"]["Currencies"]])  # available RUB without other currencies
1904        view["stat"]["totalChangesPercentRUB"] = NanoToFloat(view["raw"]["headers"]["expectedYield"]["units"], view["raw"]["headers"]["expectedYield"]["nano"]) if "expectedYield" in view["raw"]["headers"].keys() else 0.
1905        startCost = view["stat"]["portfolioCostRUB"] / (1 + view["stat"]["totalChangesPercentRUB"] / 100)
1906        view["stat"]["totalChangesRUB"] = view["stat"]["portfolioCostRUB"] - startCost
1907        view["stat"]["funds"]["rub"] = {
1908            "total": view["stat"]["availableRUB"],
1909            "totalCostRUB": view["stat"]["availableRUB"],
1910            "free": view["stat"]["availableRUB"] - view["stat"]["blockedRUB"],
1911            "freeCostRUB": view["stat"]["availableRUB"] - view["stat"]["blockedRUB"],
1912        }
1913
1914        # --- pending limit orders sector data:
1915        uniquePendingOrdersFIGIs = []  # unique FIGIs of pending limit orders to avoid many times price requests
1916        uniquePendingOrders = {}  # unique instruments with FIGIs as dictionary keys
1917
1918        for item in view["raw"]["orders"]:
1919            self._figi = item["figi"]
1920
1921            if item["figi"] not in uniquePendingOrdersFIGIs:
1922                instrument = self.SearchByFIGI(requestPrice=True)  # full raw info about instrument by FIGI, price requests only one time
1923
1924                uniquePendingOrdersFIGIs.append(item["figi"])
1925                uniquePendingOrders[item["figi"]] = instrument
1926
1927            else:
1928                instrument = uniquePendingOrders[item["figi"]]
1929
1930            if instrument:
1931                action = TKS_ORDER_DIRECTIONS[item["direction"]]
1932                orderType = TKS_ORDER_TYPES[item["orderType"]]
1933                orderState = TKS_ORDER_STATES[item["executionReportStatus"]]
1934                orderDate = item["orderDate"].replace("T", " ").replace("Z", "").split(".")[0]  # date in UTC format, e.g. "2022-12-31T23:59:59.123456Z"
1935
1936                # current instrument's price (last sellers order if buy, and last buyers order if sell):
1937                if item["direction"] == "ORDER_DIRECTION_BUY":
1938                    lastPrice = instrument["currentPrice"]["sell"][0]["price"] if instrument["currentPrice"]["sell"] else "N/A"
1939
1940                else:
1941                    lastPrice = instrument["currentPrice"]["buy"][0]["price"] if instrument["currentPrice"]["buy"] else "N/A"
1942
1943                # requested price for order execution:
1944                target = NanoToFloat(item["initialSecurityPrice"]["units"], item["initialSecurityPrice"]["nano"])
1945
1946                # necessary changes in percent to reach target from current price:
1947                changes = 100 * (lastPrice - target) / target if lastPrice != "N/A" and target > 0 else 0
1948
1949                view["stat"]["orders"].append({
1950                    "orderID": item["orderId"],  # orderId number parameter of current order
1951                    "figi": item["figi"],  # FIGI identification
1952                    "ticker": instrument["ticker"],  # ticker name by FIGI
1953                    "lotsRequested": item["lotsRequested"],  # requested lots value
1954                    "lotsExecuted": item["lotsExecuted"],  # how many lots are executed
1955                    "currentPrice": lastPrice,  # current instrument's price for defined action
1956                    "targetPrice": target,  # requested price for order execution in base currency
1957                    "baseCurrencyName": item["initialSecurityPrice"]["currency"],  # name of base currency
1958                    "percentChanges": changes,  # changes in percent to target from current price
1959                    "currency": item["currency"],  # instrument's currency name
1960                    "action": action,  # sell / buy / Unknown from TKS_ORDER_DIRECTIONS
1961                    "type": orderType,  # type of order from TKS_ORDER_TYPES
1962                    "status": orderState,  # order status from TKS_ORDER_STATES
1963                    "date": orderDate,  # string with order date and time from UTC format (without nano seconds part)
1964                })
1965
1966        # --- stop orders sector data:
1967        uniqueStopOrdersFIGIs = []  # unique FIGIs of stop orders to avoid many times price requests
1968        uniqueStopOrders = {}  # unique instruments with FIGIs as dictionary keys
1969
1970        for item in view["raw"]["stopOrders"]:
1971            self._figi = item["figi"]
1972
1973            if item["figi"] not in uniqueStopOrdersFIGIs:
1974                instrument = self.SearchByFIGI(requestPrice=True)  # full raw info about instrument by FIGI, price requests only one time
1975
1976                uniqueStopOrdersFIGIs.append(item["figi"])
1977                uniqueStopOrders[item["figi"]] = instrument
1978
1979            else:
1980                instrument = uniqueStopOrders[item["figi"]]
1981
1982            if instrument:
1983                action = TKS_STOP_ORDER_DIRECTIONS[item["direction"]]
1984                orderType = TKS_STOP_ORDER_TYPES[item["orderType"]]
1985                createDate = item["createDate"].replace("T", " ").replace("Z", "").split(".")[0]  # date in UTC format, e.g. "2022-12-31T23:59:59.123456Z"
1986
1987                # hack: server response can't contain "expirationTime" key if it is not "Until date" type of stop order
1988                if "expirationTime" in item.keys():
1989                    expType = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_DATE"]
1990                    expDate = item["expirationTime"].replace("T", " ").replace("Z", "").split(".")[0]
1991
1992                else:
1993                    expType = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_CANCEL"]
1994                    expDate = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_UNSPECIFIED"]
1995
1996                # current instrument's price (last sellers order if buy, and last buyers order if sell):
1997                if item["direction"] == "STOP_ORDER_DIRECTION_BUY":
1998                    lastPrice = instrument["currentPrice"]["sell"][0]["price"] if instrument["currentPrice"]["sell"] else "N/A"
1999
2000                else:
2001                    lastPrice = instrument["currentPrice"]["buy"][0]["price"] if instrument["currentPrice"]["buy"] else "N/A"
2002
2003                # requested price when stop-order executed:
2004                target = NanoToFloat(item["stopPrice"]["units"], item["stopPrice"]["nano"])
2005
2006                # price for limit-order, set up when stop-order executed:
2007                limit = NanoToFloat(item["price"]["units"], item["price"]["nano"])
2008
2009                # necessary changes in percent to reach target from current price:
2010                changes = 100 * (lastPrice - target) / target if lastPrice != "N/A" and target > 0 else 0
2011
2012                view["stat"]["stopOrders"].append({
2013                    "orderID": item["stopOrderId"],  # stopOrderId number parameter of current stop-order
2014                    "figi": item["figi"],  # FIGI identification
2015                    "ticker": instrument["ticker"],  # ticker name by FIGI
2016                    "lotsRequested": item["lotsRequested"],  # requested lots value
2017                    "currentPrice": lastPrice,  # current instrument's price for defined action
2018                    "targetPrice": target,  # requested price for stop-order execution in base currency
2019                    "limitPrice": limit,  # price for limit-order, set up when stop-order executed, 0 if market order
2020                    "baseCurrencyName": item["stopPrice"]["currency"],  # name of base currency
2021                    "percentChanges": changes,  # changes in percent to target from current price
2022                    "currency": item["currency"],  # instrument's currency name
2023                    "action": action,  # sell / buy / Unknown from TKS_STOP_ORDER_DIRECTIONS
2024                    "type": orderType,  # type of order from TKS_STOP_ORDER_TYPES
2025                    "expType": expType,  # expiration type of stop-order from TKS_STOP_ORDER_EXPIRATION_TYPES
2026                    "createDate": createDate,  # string with created order date and time from UTC format (without nano seconds part)
2027                    "expDate": expDate,  # string with expiration order date and time from UTC format (without nano seconds part)
2028                })
2029
2030        # --- calculating data for analytics section:
2031        # portfolio distribution by assets:
2032        view["analytics"]["distrByAssets"] = {
2033            "Ruble": {
2034                "uniques": 1,
2035                "cost": view["stat"]["availableRUB"],
2036                "percent": 100 * view["stat"]["availableRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2037            },
2038            "Currencies": {
2039                "uniques": len(view["stat"]["Currencies"]),  # all foreign currencies without RUB
2040                "cost": view["stat"]["allCurrenciesCostRUB"] - view["stat"]["availableRUB"],
2041                "percent": 100 * (view["stat"]["allCurrenciesCostRUB"] - view["stat"]["availableRUB"]) / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2042            },
2043            "Shares": {
2044                "uniques": len(view["stat"]["Shares"]),
2045                "cost": view["stat"]["sharesCostRUB"],
2046                "percent": 100 * view["stat"]["sharesCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2047            },
2048            "Bonds": {
2049                "uniques": len(view["stat"]["Bonds"]),
2050                "cost": view["stat"]["bondsCostRUB"],
2051                "percent": 100 * view["stat"]["bondsCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2052            },
2053            "Etfs": {
2054                "uniques": len(view["stat"]["Etfs"]),
2055                "cost": view["stat"]["etfsCostRUB"],
2056                "percent": 100 * view["stat"]["etfsCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2057            },
2058            "Futures": {
2059                "uniques": len(view["stat"]["Futures"]),
2060                "cost": view["stat"]["futuresCostRUB"],
2061                "percent": 100 * view["stat"]["futuresCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2062            },
2063        }
2064
2065        # portfolio distribution by companies:
2066        view["analytics"]["distrByCompanies"]["All money cash"] = {
2067            "ticker": "",
2068            "cost": view["stat"]["allCurrenciesCostRUB"],
2069            "percent": 100 * view["stat"]["allCurrenciesCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2070        }
2071        view["analytics"]["distrByCompanies"].update(byComp)
2072
2073        # portfolio distribution by sectors:
2074        view["analytics"]["distrBySectors"]["All money cash"] = {
2075            "cost": view["analytics"]["distrByCompanies"]["All money cash"]["cost"],
2076            "percent": view["analytics"]["distrByCompanies"]["All money cash"]["percent"],
2077        }
2078        view["analytics"]["distrBySectors"].update(bySect)
2079
2080        # portfolio distribution by currencies:
2081        if "rub" not in view["analytics"]["distrByCurrencies"].keys():
2082            view["analytics"]["distrByCurrencies"]["rub"] = {"name": "Российский рубль", "cost": 0, "percent": 0}
2083
2084            if self.moreDebug:
2085                uLogger.debug("Fast hack to avoid issues #71 in `Portfolio distribution by currencies` section. Server not returned current available rubles!")
2086
2087        view["analytics"]["distrByCurrencies"].update(byCurr)
2088        view["analytics"]["distrByCurrencies"]["rub"]["cost"] += view["analytics"]["distrByAssets"]["Ruble"]["cost"]
2089        view["analytics"]["distrByCurrencies"]["rub"]["percent"] += view["analytics"]["distrByAssets"]["Ruble"]["percent"]
2090
2091        # portfolio distribution by countries:
2092        if "[RU] Российская Федерация" not in view["analytics"]["distrByCountries"].keys():
2093            view["analytics"]["distrByCountries"]["[RU] Российская Федерация"] = {"cost": 0, "percent": 0}
2094
2095            if self.moreDebug:
2096                uLogger.debug("Fast hack to avoid issues #71 in `Portfolio distribution by countries` section. Server not returned current available rubles!")
2097
2098        view["analytics"]["distrByCountries"].update(byCountry)
2099        view["analytics"]["distrByCountries"]["[RU] Российская Федерация"]["cost"] += view["analytics"]["distrByAssets"]["Ruble"]["cost"]
2100        view["analytics"]["distrByCountries"]["[RU] Российская Федерация"]["percent"] += view["analytics"]["distrByAssets"]["Ruble"]["percent"]
2101
2102        # --- Prepare text statistics overview in human-readable:
2103        if show:
2104            actualOnDate = datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)
2105
2106            # Whatever the value `details`, header not changes:
2107            info = [
2108                "# Client's portfolio\n\n",
2109                "* **Actual on date:** [{} UTC]\n".format(actualOnDate),
2110                "* **Account ID:** [{}]\n".format(self.accountId),
2111            ]
2112
2113            if details in ["full", "positions", "digest"]:
2114                info.extend([
2115                    "* **Portfolio cost:** {:.2f} RUB\n".format(view["stat"]["portfolioCostRUB"]),
2116                    "* **Changes:** {}{:.2f} RUB ({}{:.2f}%)\n\n".format(
2117                        "+" if view["stat"]["totalChangesRUB"] > 0 else "",
2118                        view["stat"]["totalChangesRUB"],
2119                        "+" if view["stat"]["totalChangesPercentRUB"] > 0 else "",
2120                        view["stat"]["totalChangesPercentRUB"],
2121                    ),
2122                ])
2123
2124            if details in ["full", "positions"]:
2125                info.extend([
2126                    "## Open positions\n\n",
2127                    "| Ticker [FIGI]               | Volume (blocked)                | Lots     | Curr. price  | Avg. price   | Current volume cost | Profit (%)                   |\n",
2128                    "|-----------------------------|---------------------------------|----------|--------------|--------------|---------------------|------------------------------|\n",
2129                    "| **Ruble:**                  | {:>31} |          |              |              |                     |                              |\n".format(
2130                        "{:.2f} ({:.2f}) rub".format(
2131                            view["stat"]["availableRUB"],
2132                            view["stat"]["blockedRUB"],
2133                        )
2134                    )
2135                ])
2136
2137                def _SplitStr(CostRUB: float = 0, typeStr: str = "", noTradeStr: str = "") -> list:
2138                    return [
2139                        "|                             |                                 |          |              |              |                     |                              |\n",
2140                        "| {:<27} |                                 |          |              |              | {:>19} |                              |\n".format(
2141                            noTradeStr if noTradeStr else typeStr,
2142                            "" if noTradeStr else "{:.2f} RUB".format(CostRUB),
2143                        ),
2144                    ]
2145
2146                def _InfoStr(data: dict, isCurr: bool = False) -> str:
2147                    return "| {:<27} | {:>31} | {:<8} | {:>12} | {:>12} | {:>19} | {:<28} |\n".format(
2148                        "{} [{}]".format(data["ticker"], data["figi"]),
2149                        "{:.2f} ({:.2f}) {}".format(
2150                            data["volume"],
2151                            data["blocked"],
2152                            data["currency"],
2153                        ) if isCurr else "{:.0f} ({:.0f})".format(
2154                            data["volume"],
2155                            data["blocked"],
2156                        ),
2157                        "—" if isCurr else "{:.4f}".format(data["lots"]).rstrip("0").rstrip("."),
2158                        "{:.2f} {}".format(data["currentPrice"], data["baseCurrencyName"]) if data["currentPrice"] > 0 else "n/a",
2159                        "{:.2f} {}".format(data["average"], data["baseCurrencyName"]) if data["average"] > 0 else "n/a",
2160                        "{:.2f} {}".format(data["cost"], data["baseCurrencyName"]),
2161                        "{}{:.2f} {} ({}{:.2f}%)".format(
2162                            "+" if data["profit"] > 0 else "",
2163                            data["profit"], data["baseCurrencyName"],
2164                            "+" if data["percentProfit"] > 0 else "",
2165                            data["percentProfit"],
2166                        ),
2167                    )
2168
2169                # --- Show currencies section:
2170                if view["stat"]["Currencies"]:
2171                    info.extend(_SplitStr(CostRUB=view["analytics"]["distrByAssets"]["Currencies"]["cost"], typeStr="**Currencies:**"))
2172                    for item in view["stat"]["Currencies"]:
2173                        info.append(_InfoStr(item, isCurr=True))
2174
2175                else:
2176                    info.extend(_SplitStr(noTradeStr="**Currencies:** no trades"))
2177
2178                # --- Show shares section:
2179                if view["stat"]["Shares"]:
2180                    info.extend(_SplitStr(CostRUB=view["stat"]["sharesCostRUB"], typeStr="**Shares:**"))
2181
2182                    for item in view["stat"]["Shares"]:
2183                        info.append(_InfoStr(item))
2184
2185                else:
2186                    info.extend(_SplitStr(noTradeStr="**Shares:** no trades"))
2187
2188                # --- Show bonds section:
2189                if view["stat"]["Bonds"]:
2190                    info.extend(_SplitStr(CostRUB=view["stat"]["bondsCostRUB"], typeStr="**Bonds:**"))
2191
2192                    for item in view["stat"]["Bonds"]:
2193                        info.append(_InfoStr(item))
2194
2195                else:
2196                    info.extend(_SplitStr(noTradeStr="**Bonds:** no trades"))
2197
2198                # --- Show etfs section:
2199                if view["stat"]["Etfs"]:
2200                    info.extend(_SplitStr(CostRUB=view["stat"]["etfsCostRUB"], typeStr="**Etfs:**"))
2201
2202                    for item in view["stat"]["Etfs"]:
2203                        info.append(_InfoStr(item))
2204
2205                else:
2206                    info.extend(_SplitStr(noTradeStr="**Etfs:** no trades"))
2207
2208                # --- Show futures section:
2209                if view["stat"]["Futures"]:
2210                    info.extend(_SplitStr(CostRUB=view["stat"]["futuresCostRUB"], typeStr="**Futures:**"))
2211
2212                    for item in view["stat"]["Futures"]:
2213                        info.append(_InfoStr(item))
2214
2215                else:
2216                    info.extend(_SplitStr(noTradeStr="**Futures:** no trades"))
2217
2218            if details in ["full", "orders"]:
2219                # --- Show pending limit orders section:
2220                if view["stat"]["orders"]:
2221                    info.extend([
2222                        "\n## Opened pending limit-orders: [{}]\n".format(len(view["stat"]["orders"])),
2223                        "\n| Ticker [FIGI]               | Order ID       | Lots (exec.) | Current price (% delta) | Target price  | Action    | Type      | Create date (UTC)       |\n",
2224                        "|-----------------------------|----------------|--------------|-------------------------|---------------|-----------|-----------|-------------------------|\n",
2225                    ])
2226
2227                    for item in view["stat"]["orders"]:
2228                        info.append("| {:<27} | {:<14} | {:<12} | {:>23} | {:>13} | {:<9} | {:<9} | {:<23} |\n".format(
2229                            "{} [{}]".format(item["ticker"], item["figi"]),
2230                            item["orderID"],
2231                            "{} ({})".format(item["lotsRequested"], item["lotsExecuted"]),
2232                            "{} {} ({}{:.2f}%)".format(
2233                                "{}".format(item["currentPrice"]) if isinstance(item["currentPrice"], str) else "{:.2f}".format(float(item["currentPrice"])),
2234                                item["baseCurrencyName"],
2235                                "+" if item["percentChanges"] > 0 else "",
2236                                float(item["percentChanges"]),
2237                            ),
2238                            "{:.2f} {}".format(float(item["targetPrice"]), item["baseCurrencyName"]),
2239                            item["action"],
2240                            item["type"],
2241                            item["date"],
2242                        ))
2243
2244                else:
2245                    info.append("\n## Total pending limit-orders: [0]\n")
2246
2247                # --- Show stop orders section:
2248                if view["stat"]["stopOrders"]:
2249                    info.extend([
2250                        "\n## Opened stop-orders: [{}]\n".format(len(view["stat"]["stopOrders"])),
2251                        "\n| Ticker [FIGI]               | Stop order ID                        | Lots   | Current price (% delta) | Target price  | Limit price   | Action    | Type        | Expire type  | Create date (UTC)   | Expiration (UTC)    |\n",
2252                        "|-----------------------------|--------------------------------------|--------|-------------------------|---------------|---------------|-----------|-------------|--------------|---------------------|---------------------|\n",
2253                    ])
2254
2255                    for item in view["stat"]["stopOrders"]:
2256                        info.append("| {:<27} | {:<14} | {:<6} | {:>23} | {:>13} | {:>13} | {:<9} | {:<11} | {:<12} | {:<19} | {:<19} |\n".format(
2257                            "{} [{}]".format(item["ticker"], item["figi"]),
2258                            item["orderID"],
2259                            item["lotsRequested"],
2260                            "{} {} ({}{:.2f}%)".format(
2261                                "{}".format(item["currentPrice"]) if isinstance(item["currentPrice"], str) else "{:.2f}".format(float(item["currentPrice"])),
2262                                item["baseCurrencyName"],
2263                                "+" if item["percentChanges"] > 0 else "",
2264                                float(item["percentChanges"]),
2265                            ),
2266                            "{:.2f} {}".format(float(item["targetPrice"]), item["baseCurrencyName"]),
2267                            "{:.2f} {}".format(float(item["limitPrice"]), item["baseCurrencyName"]) if item["limitPrice"] and item["limitPrice"] != item["targetPrice"] else TKS_ORDER_TYPES["ORDER_TYPE_MARKET"],
2268                            item["action"],
2269                            item["type"],
2270                            item["expType"],
2271                            item["createDate"],
2272                            item["expDate"],
2273                        ))
2274
2275                else:
2276                    info.append("\n## Total stop-orders: [0]\n")
2277
2278            if details in ["full", "analytics"]:
2279                # -- Show analytics section:
2280                if view["stat"]["portfolioCostRUB"] > 0:
2281                    info.extend([
2282                        "\n# Analytics\n\n"
2283                        "* **Actual on date:** [{} UTC]\n".format(actualOnDate),
2284                        "* **Current total portfolio cost:** {:.2f} RUB\n".format(view["stat"]["portfolioCostRUB"]),
2285                        "* **Changes:** {}{:.2f} RUB ({}{:.2f}%)\n".format(
2286                            "+" if view["stat"]["totalChangesRUB"] > 0 else "",
2287                            view["stat"]["totalChangesRUB"],
2288                            "+" if view["stat"]["totalChangesPercentRUB"] > 0 else "",
2289                            view["stat"]["totalChangesPercentRUB"],
2290                        ),
2291                        "\n## Portfolio distribution by assets\n"
2292                        "\n| Type                               | Uniques | Percent | Current cost       |\n",
2293                        "|------------------------------------|---------|---------|--------------------|\n",
2294                    ])
2295
2296                    for key in view["analytics"]["distrByAssets"].keys():
2297                        if view["analytics"]["distrByAssets"][key]["cost"] > 0:
2298                            info.append("| {:<34} | {:<7} | {:<7} | {:<18} |\n".format(
2299                                key,
2300                                view["analytics"]["distrByAssets"][key]["uniques"],
2301                                "{:.2f}%".format(view["analytics"]["distrByAssets"][key]["percent"]),
2302                                "{:.2f} rub".format(view["analytics"]["distrByAssets"][key]["cost"]),
2303                            ))
2304
2305                    aSepLine = "|----------------------------------------------|---------|--------------------|\n"
2306
2307                    info.extend([
2308                        "\n## Portfolio distribution by companies\n"
2309                        "\n| Company                                      | Percent | Current cost       |\n",
2310                        aSepLine,
2311                    ])
2312
2313                    for company in view["analytics"]["distrByCompanies"].keys():
2314                        if view["analytics"]["distrByCompanies"][company]["cost"] > 0:
2315                            info.append("| {:<44} | {:<7} | {:<18} |\n".format(
2316                                "{}{}".format(
2317                                    "[{}] ".format(view["analytics"]["distrByCompanies"][company]["ticker"]) if view["analytics"]["distrByCompanies"][company]["ticker"] else "",
2318                                    company,
2319                                ),
2320                                "{:.2f}%".format(view["analytics"]["distrByCompanies"][company]["percent"]),
2321                                "{:.2f} rub".format(view["analytics"]["distrByCompanies"][company]["cost"]),
2322                            ))
2323
2324                    info.extend([
2325                        "\n## Portfolio distribution by sectors\n"
2326                        "\n| Sector                                       | Percent | Current cost       |\n",
2327                        aSepLine,
2328                    ])
2329
2330                    for sector in view["analytics"]["distrBySectors"].keys():
2331                        if view["analytics"]["distrBySectors"][sector]["cost"] > 0:
2332                            info.append("| {:<44} | {:<7} | {:<18} |\n".format(
2333                                sector,
2334                                "{:.2f}%".format(view["analytics"]["distrBySectors"][sector]["percent"]),
2335                                "{:.2f} rub".format(view["analytics"]["distrBySectors"][sector]["cost"]),
2336                            ))
2337
2338                    info.extend([
2339                        "\n## Portfolio distribution by currencies\n"
2340                        "\n| Instruments currencies                       | Percent | Current cost       |\n",
2341                        aSepLine,
2342                    ])
2343
2344                    for curr in view["analytics"]["distrByCurrencies"].keys():
2345                        if view["analytics"]["distrByCurrencies"][curr]["cost"] > 0:
2346                            info.append("| {:<44} | {:<7} | {:<18} |\n".format(
2347                                "[{}] {}".format(curr, view["analytics"]["distrByCurrencies"][curr]["name"]),
2348                                "{:.2f}%".format(view["analytics"]["distrByCurrencies"][curr]["percent"]),
2349                                "{:.2f} rub".format(view["analytics"]["distrByCurrencies"][curr]["cost"]),
2350                            ))
2351
2352                    info.extend([
2353                        "\n## Portfolio distribution by countries\n"
2354                        "\n| Assets by country                            | Percent | Current cost       |\n",
2355                        aSepLine,
2356                    ])
2357
2358                    for country in view["analytics"]["distrByCountries"].keys():
2359                        if view["analytics"]["distrByCountries"][country]["cost"] > 0:
2360                            info.append("| {:<44} | {:<7} | {:<18} |\n".format(
2361                                country,
2362                                "{:.2f}%".format(view["analytics"]["distrByCountries"][country]["percent"]),
2363                                "{:.2f} rub".format(view["analytics"]["distrByCountries"][country]["cost"]),
2364                            ))
2365
2366            if details in ["full", "calendar"]:
2367                # -- Show bonds payment calendar section:
2368                if view["stat"]["Bonds"]:
2369                    bondTickers = [item["ticker"] for item in view["stat"]["Bonds"]]
2370                    view["analytics"]["bondsCalendar"] = self.ExtendBondsData(instruments=bondTickers, xlsx=False)
2371                    info.append("\n" + self.ShowBondsCalendar(extBonds=view["analytics"]["bondsCalendar"], show=False))
2372
2373                else:
2374                    info.append("\n# Bond payments calendar\n\nNo bonds in the portfolio to create payments calendar\n")
2375
2376            infoText = "".join(info)
2377
2378            uLogger.info(infoText)
2379
2380            if details == "full" and self.overviewFile:
2381                filename = self.overviewFile
2382
2383            elif details == "digest" and self.overviewDigestFile:
2384                filename = self.overviewDigestFile
2385
2386            elif details == "positions" and self.overviewPositionsFile:
2387                filename = self.overviewPositionsFile
2388
2389            elif details == "orders" and self.overviewOrdersFile:
2390                filename = self.overviewOrdersFile
2391
2392            elif details == "analytics" and self.overviewAnalyticsFile:
2393                filename = self.overviewAnalyticsFile
2394
2395            elif details == "calendar" and self.overviewBondsCalendarFile:
2396                filename = self.overviewBondsCalendarFile
2397
2398            else:
2399                filename = ""
2400
2401            if filename:
2402                with open(filename, "w", encoding="UTF-8") as fH:
2403                    fH.write(infoText)
2404
2405                uLogger.info("Client's portfolio was saved to file: [{}]".format(os.path.abspath(filename)))
2406
2407                if self.useHTMLReports:
2408                    htmlFilePath = filename.replace(".md", ".html") if filename.endswith(".md") else filename + ".html"
2409                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
2410                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Client's portfolio", commonCSS=COMMON_CSS, markdown=infoText))
2411
2412                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
2413
2414        return view
2415
2416    def Deals(self, start: str = None, end: str = None, show: bool = False, showCancelled: bool = True) -> tuple[list[dict], dict]:
2417        """
2418        Returns history operations between two given dates for current `accountId`.
2419        If `reportFile` string is not empty then also save human-readable report.
2420        Shows some statistical data of closed positions.
2421
2422        :param start: see docstring in `TradeRoutines.GetDatesAsString()` method.
2423        :param end: see docstring in `TradeRoutines.GetDatesAsString()` method.
2424        :param show: if `True` then also prints all records to the console.
2425        :param showCancelled: if `False` then remove information about cancelled operations from the deals report.
2426        :return: original list of dictionaries with history of deals records from API ("operations" key):
2427                 https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetOperations
2428                 and dictionary with custom stats: operations in different currencies, withdrawals, incomes etc.
2429        """
2430        if self.accountId is None or not self.accountId:
2431            uLogger.error("Variable `accountId` must be defined for using this method!")
2432            raise Exception("Account ID required")
2433
2434        startDate, endDate = GetDatesAsString(start, end, userFormat=TKS_DATE_FORMAT, outputFormat=TKS_DATE_TIME_FORMAT)  # Example: ("2000-01-01T00:00:00Z", "2022-12-31T23:59:59Z")
2435
2436        uLogger.debug("Requesting history of a client's operations. Wait, please...")
2437
2438        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetOperations
2439        dealsURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetOperations"
2440        self.body = str({"accountId": self.accountId, "from": startDate, "to": endDate})
2441        ops = self.SendAPIRequest(dealsURL, reqType="POST")["operations"]  # list of dict: operations returns by broker
2442        customStat = {}  # custom statistics in additional to responseJSON
2443
2444        # --- output report in human-readable format:
2445        if show or self.reportFile:
2446            splitLine1 = "|                            |                               |                              |                      |                        |\n"  # Summary section
2447            splitLine2 = "|                     |              |              |            |           |                 |            |                                                                    |\n"  # Operations section
2448            nextDay = ""
2449
2450            info = ["# Client's operations\n\n* **Period:** from [{}] to [{}]\n\n## Summary (operations executed only)\n\n".format(startDate.split("T")[0], endDate.split("T")[0])]
2451
2452            if len(ops) > 0:
2453                customStat = {
2454                    "opsCount": 0,  # total operations count
2455                    "buyCount": 0,  # buy operations
2456                    "sellCount": 0,  # sell operations
2457                    "buyTotal": {"rub": 0.},  # Buy sums in different currencies
2458                    "sellTotal": {"rub": 0.},  # Sell sums in different currencies
2459                    "payIn": {"rub": 0.},  # Deposit brokerage account
2460                    "payOut": {"rub": 0.},  # Withdrawals
2461                    "divs": {"rub": 0.},  # Dividends income
2462                    "coupons": {"rub": 0.},  # Coupon's income
2463                    "brokerCom": {"rub": 0.},  # Service commissions
2464                    "serviceCom": {"rub": 0.},  # Service commissions
2465                    "marginCom": {"rub": 0.},  # Margin commissions
2466                    "allTaxes": {"rub": 0.},  # Sum of withholding taxes and corrections
2467                }
2468
2469                # --- calculating statistics depends on operations type in TKS_OPERATION_TYPES:
2470                for item in ops:
2471                    if item["state"] == "OPERATION_STATE_EXECUTED":
2472                        payment = NanoToFloat(item["payment"]["units"], item["payment"]["nano"])
2473
2474                        # count buy operations:
2475                        if "_BUY" in item["operationType"]:
2476                            customStat["buyCount"] += 1
2477
2478                            if item["payment"]["currency"] in customStat["buyTotal"].keys():
2479                                customStat["buyTotal"][item["payment"]["currency"]] += payment
2480
2481                            else:
2482                                customStat["buyTotal"][item["payment"]["currency"]] = payment
2483
2484                        # count sell operations:
2485                        elif "_SELL" in item["operationType"]:
2486                            customStat["sellCount"] += 1
2487
2488                            if item["payment"]["currency"] in customStat["sellTotal"].keys():
2489                                customStat["sellTotal"][item["payment"]["currency"]] += payment
2490
2491                            else:
2492                                customStat["sellTotal"][item["payment"]["currency"]] = payment
2493
2494                        # count incoming operations:
2495                        elif item["operationType"] in ["OPERATION_TYPE_INPUT"]:
2496                            if item["payment"]["currency"] in customStat["payIn"].keys():
2497                                customStat["payIn"][item["payment"]["currency"]] += payment
2498
2499                            else:
2500                                customStat["payIn"][item["payment"]["currency"]] = payment
2501
2502                        # count withdrawals operations:
2503                        elif item["operationType"] in ["OPERATION_TYPE_OUTPUT"]:
2504                            if item["payment"]["currency"] in customStat["payOut"].keys():
2505                                customStat["payOut"][item["payment"]["currency"]] += payment
2506
2507                            else:
2508                                customStat["payOut"][item["payment"]["currency"]] = payment
2509
2510                        # count dividends income:
2511                        elif item["operationType"] in ["OPERATION_TYPE_DIVIDEND", "OPERATION_TYPE_DIVIDEND_TRANSFER", "OPERATION_TYPE_DIV_EXT"]:
2512                            if item["payment"]["currency"] in customStat["divs"].keys():
2513                                customStat["divs"][item["payment"]["currency"]] += payment
2514
2515                            else:
2516                                customStat["divs"][item["payment"]["currency"]] = payment
2517
2518                        # count coupon's income:
2519                        elif item["operationType"] in ["OPERATION_TYPE_COUPON", "OPERATION_TYPE_BOND_REPAYMENT_FULL", "OPERATION_TYPE_BOND_REPAYMENT"]:
2520                            if item["payment"]["currency"] in customStat["coupons"].keys():
2521                                customStat["coupons"][item["payment"]["currency"]] += payment
2522
2523                            else:
2524                                customStat["coupons"][item["payment"]["currency"]] = payment
2525
2526                        # count broker commissions:
2527                        elif item["operationType"] in ["OPERATION_TYPE_BROKER_FEE", "OPERATION_TYPE_SUCCESS_FEE", "OPERATION_TYPE_TRACK_MFEE", "OPERATION_TYPE_TRACK_PFEE"]:
2528                            if item["payment"]["currency"] in customStat["brokerCom"].keys():
2529                                customStat["brokerCom"][item["payment"]["currency"]] += payment
2530
2531                            else:
2532                                customStat["brokerCom"][item["payment"]["currency"]] = payment
2533
2534                        # count service commissions:
2535                        elif item["operationType"] in ["OPERATION_TYPE_SERVICE_FEE"]:
2536                            if item["payment"]["currency"] in customStat["serviceCom"].keys():
2537                                customStat["serviceCom"][item["payment"]["currency"]] += payment
2538
2539                            else:
2540                                customStat["serviceCom"][item["payment"]["currency"]] = payment
2541
2542                        # count margin commissions:
2543                        elif item["operationType"] in ["OPERATION_TYPE_MARGIN_FEE"]:
2544                            if item["payment"]["currency"] in customStat["marginCom"].keys():
2545                                customStat["marginCom"][item["payment"]["currency"]] += payment
2546
2547                            else:
2548                                customStat["marginCom"][item["payment"]["currency"]] = payment
2549
2550                        # count withholding taxes:
2551                        elif "_TAX" in item["operationType"]:
2552                            if item["payment"]["currency"] in customStat["allTaxes"].keys():
2553                                customStat["allTaxes"][item["payment"]["currency"]] += payment
2554
2555                            else:
2556                                customStat["allTaxes"][item["payment"]["currency"]] = payment
2557
2558                        else:
2559                            continue
2560
2561                customStat["opsCount"] += customStat["buyCount"] + customStat["sellCount"]
2562
2563                # --- view "Actions" lines:
2564                info.extend([
2565                    "| Report sections            |                               |                              |                      |                        |\n",
2566                    "|----------------------------|-------------------------------|------------------------------|----------------------|------------------------|\n",
2567                    "| **Actions:**               | Trades: {:<21} | Trading volumes:             |                      |                        |\n".format(customStat["opsCount"]),
2568                    "|                            |   Buy: {:<22} | {:<28} |                      |                        |\n".format(
2569                        "{} ({:.1f}%)".format(customStat["buyCount"], 100 * customStat["buyCount"] / customStat["opsCount"]) if customStat["opsCount"] != 0 else 0,
2570                        "  rub, buy: {:<16}".format("{:.2f}".format(customStat["buyTotal"]["rub"])) if customStat["buyTotal"]["rub"] != 0 else "  —",
2571                    ),
2572                    "|                            |   Sell: {:<21} | {:<28} |                      |                        |\n".format(
2573                        "{} ({:.1f}%)".format(customStat["sellCount"], 100 * customStat["sellCount"] / customStat["opsCount"]) if customStat["opsCount"] != 0 else 0,
2574                        "  rub, sell: {:<13}".format("+{:.2f}".format(customStat["sellTotal"]["rub"])) if customStat["sellTotal"]["rub"] != 0 else "  —",
2575                    ),
2576                ])
2577
2578                opsKeys = sorted(list(set(list(customStat["buyTotal"].keys()) + list(customStat["sellTotal"].keys()))))
2579                for key in opsKeys:
2580                    if key == "rub":
2581                        continue
2582
2583                    info.extend([
2584                        "|                            |                               | {:<28} |                      |                        |\n".format(
2585                            "  {}, buy: {:<16}".format(key, "{:.2f}".format(customStat["buyTotal"][key]) if key and key in customStat["buyTotal"].keys() and customStat["buyTotal"][key] != 0 else 0)
2586                        ),
2587                        "|                            |                               | {:<28} |                      |                        |\n".format(
2588                            "  {}, sell: {:<13}".format(key, "+{:.2f}".format(customStat["sellTotal"][key]) if key and key in customStat["sellTotal"].keys() and customStat["sellTotal"][key] != 0 else 0)
2589                        ),
2590                    ])
2591
2592                info.append(splitLine1)
2593
2594                def _InfoStr(data1: dict, data2: dict, data3: dict, data4: dict, cur: str = "") -> str:
2595                    return "|                            | {:<29} | {:<28} | {:<20} | {:<22} |\n".format(
2596                            "  {}: {}{:.2f}".format(cur, "+" if data1[cur] > 0 else "", data1[cur]) if cur and cur in data1.keys() and data1[cur] != 0 else "  —",
2597                            "  {}: {}{:.2f}".format(cur, "+" if data2[cur] > 0 else "", data2[cur]) if cur and cur in data2.keys() and data2[cur] != 0 else "  —",
2598                            "  {}: {}{:.2f}".format(cur, "+" if data3[cur] > 0 else "", data3[cur]) if cur and cur in data3.keys() and data3[cur] != 0 else "  —",
2599                            "  {}: {}{:.2f}".format(cur, "+" if data4[cur] > 0 else "", data4[cur]) if cur and cur in data4.keys() and data4[cur] != 0 else "  —",
2600                    )
2601
2602                # --- view "Payments" lines:
2603                info.append("| **Payments:**              | Deposit on broker account:    | Withdrawals:                 | Dividends income:    | Coupons income:        |\n")
2604                paymentsKeys = sorted(list(set(list(customStat["payIn"].keys()) + list(customStat["payOut"].keys()) + list(customStat["divs"].keys()) + list(customStat["coupons"].keys()))))
2605
2606                for key in paymentsKeys:
2607                    info.append(_InfoStr(customStat["payIn"], customStat["payOut"], customStat["divs"], customStat["coupons"], key))
2608
2609                info.append(splitLine1)
2610
2611                # --- view "Commissions and taxes" lines:
2612                info.append("| **Commissions and taxes:** | Broker commissions:           | Service commissions:         | Margin commissions:  | All taxes/corrections: |\n")
2613                comKeys = sorted(list(set(list(customStat["brokerCom"].keys()) + list(customStat["serviceCom"].keys()) + list(customStat["marginCom"].keys()) + list(customStat["allTaxes"].keys()))))
2614
2615                for key in comKeys:
2616                    info.append(_InfoStr(customStat["brokerCom"], customStat["serviceCom"], customStat["marginCom"], customStat["allTaxes"], key))
2617
2618                info.extend([
2619                    "\n## All operations{}\n\n".format("" if showCancelled else " (without cancelled status)"),
2620                    "| Date and time       | FIGI         | Ticker       | Asset      | Value     | Payment         | Status     | Operation type                                                     |\n",
2621                    "|---------------------|--------------|--------------|------------|-----------|-----------------|------------|--------------------------------------------------------------------|\n",
2622                ])
2623
2624            else:
2625                info.append("Broker returned no operations during this period\n")
2626
2627            # --- view "Operations" section:
2628            for item in ops:
2629                if not showCancelled and TKS_OPERATION_STATES[item["state"]] == TKS_OPERATION_STATES["OPERATION_STATE_CANCELED"]:
2630                    continue
2631
2632                else:
2633                    self._figi = item["figi"]
2634                    payment = NanoToFloat(item["payment"]["units"], item["payment"]["nano"])
2635                    instrument = self.SearchByFIGI(requestPrice=False) if self._figi else {}
2636
2637                    # group of deals during one day:
2638                    if nextDay and item["date"].split("T")[0] != nextDay:
2639                        info.append(splitLine2)
2640                        nextDay = ""
2641
2642                    else:
2643                        nextDay = item["date"].split("T")[0]  # saving current day for splitting
2644
2645                    info.append("| {:<19} | {:<12} | {:<12} | {:<10} | {:<9} | {:>15} | {:<10} | {:<66} |\n".format(
2646                        item["date"].replace("T", " ").replace("Z", "").split(".")[0],
2647                        self._figi if self._figi else "—",
2648                        instrument["ticker"] if instrument else "—",
2649                        instrument["type"] if instrument else "—",
2650                        item["quantity"] if int(item["quantity"]) > 0 else "—",
2651                        "{}{:.2f} {}".format("+" if payment > 0 else "", payment, item["payment"]["currency"]) if payment != 0 else "—",
2652                        TKS_OPERATION_STATES[item["state"]],
2653                        TKS_OPERATION_TYPES[item["operationType"]],
2654                    ))
2655
2656            infoText = "".join(info)
2657
2658            if show:
2659                if self.moreDebug:
2660                    uLogger.debug("Records about history of a client's operations successfully received")
2661
2662                uLogger.info(infoText)
2663
2664            if self.reportFile:
2665                with open(self.reportFile, "w", encoding="UTF-8") as fH:
2666                    fH.write(infoText)
2667
2668                uLogger.info("History of a client's operations are saved to file: [{}]".format(os.path.abspath(self.reportFile)))
2669
2670                if self.useHTMLReports:
2671                    htmlFilePath = self.reportFile.replace(".md", ".html") if self.reportFile.endswith(".md") else self.reportFile + ".html"
2672                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
2673                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Client's operations", commonCSS=COMMON_CSS, markdown=infoText))
2674
2675                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
2676
2677        return ops, customStat
2678
2679    def History(self, start: str = None, end: str = None, interval: str = "hour", onlyMissing: bool = False, csvSep: str = ",", show: bool = False) -> pd.DataFrame:
2680        """
2681        This method returns last history candles of the current instrument defined by `ticker` or `figi` (FIGI id).
2682
2683        History returned between two given dates: `start` and `end`. Minimum requested date in the past is `1970-01-01`.
2684        Warning! Broker server used ISO UTC time by default.
2685
2686        If `historyFile` is not `None` then method save history to file, otherwise return only Pandas DataFrame.
2687        Also, `historyFile` used to update history with `onlyMissing` parameter.
2688
2689        See also: `LoadHistory()` and `ShowHistoryChart()` methods.
2690
2691        :param start: see docstring in `TradeRoutines.GetDatesAsString()` method.
2692        :param end: see docstring in `TradeRoutines.GetDatesAsString()` method.
2693        :param interval: this is a candle interval. Current available values are `"1min"`, `"5min"`, `"15min"`,
2694                         `"hour"`, `"day"`. Default: `"hour"`.
2695        :param onlyMissing: if `True` then add only last missing candles, do not request all history length from `start`.
2696                            False by default. Warning! History appends only from last candle to current time
2697                            with always update last candle!
2698        :param csvSep: separator if csv-file is used, `,` by default.
2699        :param show: if `True` then also prints Pandas DataFrame to the console.
2700        :return: Pandas DataFrame with prices history. Headers of columns are defined by default:
2701                 `["date", "time", "open", "high", "low", "close", "volume"]`.
2702        """
2703        strStartDate, strEndDate = GetDatesAsString(start, end, userFormat=TKS_DATE_FORMAT, outputFormat=TKS_DATE_TIME_FORMAT)  # example: ("2020-01-01T00:00:00Z", "2022-12-31T23:59:59Z")
2704        headers = ["date", "time", "open", "high", "low", "close", "volume"]  # sequence and names of column headers
2705        history = None  # empty pandas object for history
2706
2707        if interval not in TKS_CANDLE_INTERVALS.keys():
2708            uLogger.error("Interval parameter must be string with current available values: `1min`, `5min`, `15min`, `hour` and `day`.")
2709            raise Exception("Incorrect value")
2710
2711        if not (self._ticker or self._figi):
2712            uLogger.error("Ticker or FIGI must be defined!")
2713            raise Exception("Ticker or FIGI required")
2714
2715        if self._ticker and not self._figi:
2716            instrumentByTicker = self.SearchByTicker(requestPrice=False)
2717            self._figi = instrumentByTicker["figi"] if instrumentByTicker else ""
2718
2719        if self._figi and not self._ticker:
2720            instrumentByFIGI = self.SearchByFIGI(requestPrice=False)
2721            self._ticker = instrumentByFIGI["ticker"] if instrumentByFIGI else ""
2722
2723        dtStart = datetime.strptime(strStartDate, TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc())  # datetime object from start time string
2724        dtEnd = datetime.strptime(strEndDate, TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc())  # datetime object from end time string
2725        if interval.lower() != "day":
2726            dtEnd += timedelta(seconds=1)  # adds 1 sec for requests, because day end returned by `TradeRoutines.GetDatesAsString()` is 23:59:59
2727
2728        delta = dtEnd - dtStart  # current UTC time minus last time in file
2729        deltaMinutes = delta.days * 1440 + delta.seconds // 60  # minutes between start and end dates
2730
2731        # calculate history length in candles:
2732        length = deltaMinutes // TKS_CANDLE_INTERVALS[interval][1]
2733        if deltaMinutes % TKS_CANDLE_INTERVALS[interval][1] > 0:
2734            length += 1  # to avoid fraction time
2735
2736        # calculate data blocks count:
2737        blocks = 1 if length < TKS_CANDLE_INTERVALS[interval][2] else 1 + length // TKS_CANDLE_INTERVALS[interval][2]
2738
2739        uLogger.debug("Original requested time period in local time: from [{}] to [{}]".format(start, end))
2740        uLogger.debug("Requested time period is about from [{}] UTC to [{}] UTC".format(strStartDate, strEndDate))
2741        uLogger.debug("Calculated history length: [{}], interval: [{}]".format(length, interval))
2742        uLogger.debug("Data blocks, count: [{}], max candles in block: [{}]".format(blocks, TKS_CANDLE_INTERVALS[interval][2]))
2743        uLogger.debug("Requesting history candlesticks, ticker: [{}], FIGI: [{}]. Wait, please...".format(self._ticker, self._figi))
2744
2745        tempOld = None  # pandas object for old history, if --only-missing key present
2746        lastTime = None  # datetime object of last old candle in file
2747
2748        if onlyMissing and self.historyFile is not None and self.historyFile and os.path.exists(self.historyFile):
2749            uLogger.debug("--only-missing key present, add only last missing candles...")
2750            uLogger.debug("History file will be updated: [{}]".format(os.path.abspath(self.historyFile)))
2751
2752            tempOld = pd.read_csv(self.historyFile, sep=csvSep, header=None, names=headers)
2753
2754            tempOld["date"] = pd.to_datetime(tempOld["date"])  # load date "as is"
2755            tempOld["date"] = tempOld["date"].dt.strftime("%Y.%m.%d")  # convert date to string
2756            tempOld["time"] = pd.to_datetime(tempOld["time"])  # load time "as is"
2757            tempOld["time"] = tempOld["time"].dt.strftime("%H:%M")  # convert time to string
2758
2759            # get last datetime object from last string in file or minus 1 delta if file is empty:
2760            if len(tempOld) > 0:
2761                lastTime = datetime.strptime(tempOld.date.iloc[-1] + " " + tempOld.time.iloc[-1], "%Y.%m.%d %H:%M").replace(tzinfo=tzutc())
2762
2763            else:
2764                lastTime = dtEnd - timedelta(days=1)  # history file is empty, so last date set at -1 day
2765
2766            tempOld = tempOld[:-1]  # always remove last old candle because it may be incompletely at the current time
2767
2768        responseJSONs = []  # raw history blocks of data
2769
2770        blockEnd = dtEnd
2771        for item in range(blocks):
2772            tail = length % TKS_CANDLE_INTERVALS[interval][2] if item + 1 == blocks else TKS_CANDLE_INTERVALS[interval][2]
2773            blockStart = blockEnd - timedelta(minutes=TKS_CANDLE_INTERVALS[interval][1] * tail)
2774
2775            uLogger.debug("[Block #{}/{}] time period: [{}] UTC - [{}] UTC".format(
2776                item + 1, blocks, blockStart.strftime(TKS_DATE_TIME_FORMAT), blockEnd.strftime(TKS_DATE_TIME_FORMAT),
2777            ))
2778
2779            if blockStart == blockEnd:
2780                uLogger.debug("Skipped this zero-length block...")
2781
2782            else:
2783                # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetCandles
2784                historyURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetCandles"
2785                self.body = str({
2786                    "figi": self._figi,
2787                    "from": blockStart.strftime(TKS_DATE_TIME_FORMAT),
2788                    "to": blockEnd.strftime(TKS_DATE_TIME_FORMAT),
2789                    "interval": TKS_CANDLE_INTERVALS[interval][0]
2790                })
2791                responseJSON = self.SendAPIRequest(historyURL, reqType="POST", retry=1, pause=1)
2792
2793                if "code" in responseJSON.keys():
2794                    uLogger.debug("An issue occurred and block #{}/{} is empty".format(item + 1, blocks))
2795
2796                else:
2797                    if start is not None and (start.lower() == "yesterday" or start == end) and interval == "day" and len(responseJSON["candles"]) > 1:
2798                        responseJSON["candles"] = responseJSON["candles"][:-1]  # removes last candle for "yesterday" request
2799
2800                    responseJSONs = responseJSON["candles"] + responseJSONs  # add more old history behind newest dates
2801
2802            blockEnd = blockStart
2803
2804        printCount = len(responseJSONs)  # candles to show in console
2805        if responseJSONs:
2806            tempHistory = pd.DataFrame(
2807                data={
2808                    "date": [pd.to_datetime(item["time"]).astimezone(tzutc()) for item in responseJSONs],
2809                    "time": [pd.to_datetime(item["time"]).astimezone(tzutc()) for item in responseJSONs],
2810                    "open": [NanoToFloat(item["open"]["units"], item["open"]["nano"]) for item in responseJSONs],
2811                    "high": [NanoToFloat(item["high"]["units"], item["high"]["nano"]) for item in responseJSONs],
2812                    "low": [NanoToFloat(item["low"]["units"], item["low"]["nano"]) for item in responseJSONs],
2813                    "close": [NanoToFloat(item["close"]["units"], item["close"]["nano"]) for item in responseJSONs],
2814                    "volume": [int(item["volume"]) for item in responseJSONs],
2815                },
2816                index=range(len(responseJSONs)),
2817                columns=["date", "time", "open", "high", "low", "close", "volume"],
2818            )
2819            tempHistory["date"] = tempHistory["date"].dt.strftime("%Y.%m.%d")
2820            tempHistory["time"] = tempHistory["time"].dt.strftime("%H:%M")
2821
2822            # append only newest candles to old history if --only-missing key present:
2823            if onlyMissing and tempOld is not None and lastTime is not None:
2824                index = 0  # find start index in tempHistory data:
2825
2826                for i, item in tempHistory.iterrows():
2827                    curTime = datetime.strptime(item["date"] + " " + item["time"], "%Y.%m.%d %H:%M").replace(tzinfo=tzutc())
2828
2829                    if curTime == lastTime:
2830                        uLogger.debug("History will be updated starting from the date: [{}]".format(curTime.strftime(TKS_PRINT_DATE_TIME_FORMAT)))
2831                        index = i
2832                        printCount = index + 1
2833                        break
2834
2835                history = pd.concat([tempOld, tempHistory[index:]], ignore_index=True)
2836
2837            else:
2838                history = tempHistory  # if no `--only-missing` key then load full data from server
2839
2840            uLogger.debug("Last 3 rows of received history:\n{}".format(pd.DataFrame.to_string(history[["date", "time", "open", "high", "low", "close", "volume"]][-3:], max_cols=20, index=False)))
2841
2842        if history is not None and not history.empty:
2843            if show:
2844                uLogger.info("Here's requested history between [{}] UTC and [{}] UTC, not-empty candles count: [{}]\n{}".format(
2845                    strStartDate.replace("T", " ").replace("Z", ""), strEndDate.replace("T", " ").replace("Z", ""), len(history[-printCount:]),
2846                    pd.DataFrame.to_string(history[["date", "time", "open", "high", "low", "close", "volume"]][-printCount:], max_cols=20, index=False),
2847                ))
2848
2849        else:
2850            uLogger.warning("Received an empty candles history!")
2851
2852        if self.historyFile is not None:
2853            if history is not None and not history.empty:
2854                history.to_csv(self.historyFile, sep=csvSep, index=False, header=None)
2855                uLogger.info("Ticker [{}], FIGI [{}], tf: [{}], history saved: [{}]".format(self._ticker, self._figi, interval, os.path.abspath(self.historyFile)))
2856
2857            else:
2858                uLogger.warning("Empty history received! File NOT updated: [{}]".format(os.path.abspath(self.historyFile)))
2859
2860        else:
2861            uLogger.debug("--output key is not defined. Parsed history file not saved to file, only Pandas DataFrame returns.")
2862
2863        return history
2864
2865    def LoadHistory(self, filePath: str) -> pd.DataFrame:
2866        """
2867        Load candles history from csv-file and return Pandas DataFrame object.
2868
2869        See also: `History()` and `ShowHistoryChart()` methods.
2870
2871        :param filePath: path to csv-file to open.
2872        """
2873        loadedHistory = None  # init candles data object
2874
2875        uLogger.debug("Loading candles history with PriceGenerator module. Wait, please...")
2876
2877        if os.path.exists(filePath):
2878            loadedHistory = self.priceModel.LoadFromFile(filePath)  # load data and get chain of candles as Pandas DataFrame
2879
2880            tfStr = self.priceModel.FormattedDelta(
2881                self.priceModel.timeframe,
2882                "{days} days {hours}h {minutes}m {seconds}s",
2883            ) if self.priceModel.timeframe >= timedelta(days=1) else self.priceModel.FormattedDelta(
2884                self.priceModel.timeframe,
2885                "{hours}h {minutes}m {seconds}s",
2886            )
2887
2888            if loadedHistory is not None and not loadedHistory.empty:
2889                uLogger.info("Rows count loaded: [{}], detected timeframe of candles: [{}]. Showing some last rows:\n{}".format(
2890                    len(loadedHistory),
2891                    tfStr,
2892                    pd.DataFrame.to_string(loadedHistory[-10:], max_cols=20)),
2893                )
2894
2895            else:
2896                uLogger.warning("It was loaded an empty history! Path: [{}]".format(os.path.abspath(filePath)))
2897
2898        else:
2899            uLogger.error("File with candles history does not exist! Check the path: [{}]".format(filePath))
2900
2901        return loadedHistory
2902
2903    def ShowHistoryChart(self, candles: Union[str, pd.DataFrame] = None, interact: bool = True, openInBrowser: bool = False) -> None:
2904        """
2905        Render an HTML-file with interact or non-interact candlesticks chart. Candles may be path to the csv-file.
2906
2907        Self variable `htmlHistoryFile` can be use as html-file name to save interaction or non-interaction chart.
2908        Default: `index.html` (both for interact and non-interact candlesticks chart).
2909
2910        See also: `History()` and `LoadHistory()` methods.
2911
2912        :param candles: string to csv-file with candles in OHLCV-model or like Pandas Dataframe object.
2913        :param interact: if True (default) then chain of candlesticks will render as interactive Bokeh chart.
2914                         See examples: https://github.com/Tim55667757/PriceGenerator#overriding-parameters
2915                         If False then chain of candlesticks will render as not interactive Google Candlestick chart.
2916                         See examples: https://github.com/Tim55667757/PriceGenerator#statistics-and-chart-on-a-simple-template
2917        :param openInBrowser: if True then immediately open chart in default browser, otherwise only path to
2918                              html-file prints to console. False by default, to avoid issues with `permissions denied` to html-file.
2919        """
2920        if isinstance(candles, str):
2921            self.priceModel.prices = self.LoadHistory(filePath=candles)  # load candles chain from file
2922            self.priceModel.ticker = os.path.basename(candles)  # use filename as ticker name in PriceGenerator
2923
2924        elif isinstance(candles, pd.DataFrame):
2925            self.priceModel.prices = candles  # set candles chain from variable
2926            self.priceModel.ticker = self._ticker  # use current TKSBrokerAPI ticker as ticker name in PriceGenerator
2927
2928            if "datetime" not in candles.columns:
2929                self.priceModel.prices["datetime"] = pd.to_datetime(candles.date + ' ' + candles.time, utc=True)  # PriceGenerator uses "datetime" column with date and time
2930
2931        else:
2932            uLogger.error("`candles` variable must be path string to the csv-file with candles in OHLCV-model or like Pandas Dataframe object!")
2933            raise Exception("Incorrect value")
2934
2935        self.priceModel.horizon = len(self.priceModel.prices)  # use length of candles data as horizon in PriceGenerator
2936
2937        if interact:
2938            uLogger.debug("Rendering interactive candles chart. Wait, please...")
2939
2940            self.priceModel.RenderBokeh(fileName=self.htmlHistoryFile, viewInBrowser=openInBrowser)
2941
2942        else:
2943            uLogger.debug("Rendering non-interactive candles chart. Wait, please...")
2944
2945            self.priceModel.RenderGoogle(fileName=self.htmlHistoryFile, viewInBrowser=openInBrowser)
2946
2947        uLogger.info("Rendered candles chart: [{}]".format(os.path.abspath(self.htmlHistoryFile)))
2948
2949    def Trade(self, operation: str, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
2950        """
2951        Universal method to create market order and make deal at the current price for current `accountId`. Returns JSON data with response.
2952        If `tp` or `sl` > 0, then in additional will open stop-orders with "TP" and "SL" flags for `stopType` parameter.
2953
2954        See also: `Order()` docstring. More simple methods than `Trade()` are `Buy()` and `Sell()`.
2955
2956        :param operation: string "Buy" or "Sell".
2957        :param lots: volume, integer count of lots >= 1.
2958        :param tp: float > 0, target price for stop-order with "TP" type. It used as take profit parameter `targetPrice` in `self.Order()`.
2959        :param sl: float > 0, target price for stop-order with "SL" type. It used as stop loss parameter `targetPrice` in `self.Order()`.
2960        :param expDate: string "Undefined" by default or local date in future,
2961                        it is a string with format `%Y-%m-%d %H:%M:%S`.
2962        :return: JSON with response from broker server.
2963        """
2964        if self.accountId is None or not self.accountId:
2965            uLogger.error("Variable `accountId` must be defined for using this method!")
2966            raise Exception("Account ID required")
2967
2968        if operation is None or not operation or operation not in ("Buy", "Sell"):
2969            uLogger.error("You must define operation type only one of them: `Buy` or `Sell`!")
2970            raise Exception("Incorrect value")
2971
2972        if lots is None or lots < 1:
2973            uLogger.warning("You must define trade volume > 0: integer count of lots! For current operation lots reset to 1.")
2974            lots = 1
2975
2976        if tp is None or tp < 0:
2977            tp = 0
2978
2979        if sl is None or sl < 0:
2980            sl = 0
2981
2982        if expDate is None or not expDate:
2983            expDate = "Undefined"
2984
2985        if not (self._ticker or self._figi):
2986            uLogger.error("Ticker or FIGI must be defined!")
2987            raise Exception("Ticker or FIGI required")
2988
2989        instrument = self.SearchByTicker(requestPrice=True) if self._ticker else self.SearchByFIGI(requestPrice=True)
2990        self._ticker = instrument["ticker"]
2991        self._figi = instrument["figi"]
2992
2993        uLogger.debug("Opening [{}] market order: ticker [{}], FIGI [{}], lots [{}], TP [{:.4f}], SL [{:.4f}], expiration date of TP/SL orders [{}]. Wait, please...".format(operation, self._ticker, self._figi, lots, tp, sl, expDate))
2994
2995        openTradeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/PostOrder"
2996        self.body = str({
2997            "figi": self._figi,
2998            "quantity": str(lots),
2999            "direction": "ORDER_DIRECTION_BUY" if operation == "Buy" else "ORDER_DIRECTION_SELL",  # see: TKS_ORDER_DIRECTIONS
3000            "accountId": str(self.accountId),
3001            "orderType": "ORDER_TYPE_MARKET",  # see: TKS_ORDER_TYPES
3002        })
3003        response = self.SendAPIRequest(openTradeURL, reqType="POST", retry=0)
3004
3005        if "orderId" in response.keys():
3006            uLogger.info("[{}] market order [{}] was executed: ticker [{}], FIGI [{}], lots [{}]. Total order price: [{:.4f} {}] (with commission: [{:.2f} {}]). Average price of lot: [{:.2f} {}]".format(
3007                operation, response["orderId"],
3008                self._ticker, self._figi, lots,
3009                NanoToFloat(response["totalOrderAmount"]["units"], response["totalOrderAmount"]["nano"]), response["totalOrderAmount"]["currency"],
3010                NanoToFloat(response["initialCommission"]["units"], response["initialCommission"]["nano"]), response["initialCommission"]["currency"],
3011                NanoToFloat(response["executedOrderPrice"]["units"], response["executedOrderPrice"]["nano"]), response["executedOrderPrice"]["currency"],
3012            ))
3013
3014            if tp > 0:
3015                self.Order(operation="Sell" if operation == "Buy" else "Buy", orderType="Stop", lots=lots, targetPrice=tp, limitPrice=tp, stopType="TP", expDate=expDate)
3016
3017            if sl > 0:
3018                self.Order(operation="Sell" if operation == "Buy" else "Buy", orderType="Stop", lots=lots, targetPrice=sl, limitPrice=sl, stopType="SL", expDate=expDate)
3019
3020        else:
3021            uLogger.warning("Not `oK` status received! Market order not executed. See full debug log and try again open order later.")
3022
3023        return response
3024
3025    def Buy(self, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
3026        """
3027        More simple method than `Trade()`. Create `Buy` market order and make deal at the current price. Returns JSON data with response.
3028        If `tp` or `sl` > 0, then in additional will opens stop-orders with "TP" and "SL" flags for `stopType` parameter.
3029
3030        See also: `Order()` and `Trade()` docstrings.
3031
3032        :param lots: volume, integer count of lots >= 1.
3033        :param tp: float > 0, take profit price of stop-order.
3034        :param sl: float > 0, stop loss price of stop-order.
3035        :param expDate: it's a local date in future.
3036                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3037        :return: JSON with response from broker server.
3038        """
3039        return self.Trade(operation="Buy", lots=lots, tp=tp, sl=sl, expDate=expDate)
3040
3041    def Sell(self, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
3042        """
3043        More simple method than `Trade()`. Create `Sell` market order and make deal at the current price. Returns JSON data with response.
3044        If `tp` or `sl` > 0, then in additional will open stop-orders with "TP" and "SL" flags for `stopType` parameter.
3045
3046        See also: `Order()` and `Trade()` docstrings.
3047
3048        :param lots: volume, integer count of lots >= 1.
3049        :param tp: float > 0, take profit price of stop-order.
3050        :param sl: float > 0, stop loss price of stop-order.
3051        :param expDate: it's a local date in the future.
3052                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3053        :return: JSON with response from broker server.
3054        """
3055        return self.Trade(operation="Sell", lots=lots, tp=tp, sl=sl, expDate=expDate)
3056
3057    def CloseTrades(self, instruments: list[str], portfolio: dict = None) -> None:
3058        """
3059        Close position of given instruments.
3060
3061        :param instruments: list of instruments defined by tickers or FIGIs that must be closed.
3062        :param portfolio: pre-received dictionary with open trades, returned by `Overview()` method.
3063                         This avoids unnecessary downloading data from the server.
3064        """
3065        if instruments is None or not instruments:
3066            uLogger.error("List of tickers or FIGIs must be defined for using this method!")
3067            raise Exception("Ticker or FIGI required")
3068
3069        if isinstance(instruments, str):
3070            instruments = [instruments]
3071
3072        uniqueInstruments = self.GetUniqueFIGIs(instruments)
3073        if uniqueInstruments:
3074            if portfolio is None or not portfolio:
3075                portfolio = self.Overview(show=False)
3076
3077            allOpened = [item["figi"] for iType in TKS_INSTRUMENTS for item in portfolio["stat"][iType]]
3078            uLogger.debug("All opened instruments by it's FIGI: {}".format(", ".join(allOpened)))
3079
3080            for self._figi in uniqueInstruments:
3081                if self._figi not in allOpened:
3082                    uLogger.warning("Instrument with FIGI [{}] not in open positions list!".format(self._figi))
3083                    continue
3084
3085                # search open trade info about instrument by ticker:
3086                instrument = {}
3087                for iType in TKS_INSTRUMENTS:
3088                    if instrument:
3089                        break
3090
3091                    for item in portfolio["stat"][iType]:
3092                        if item["figi"] == self._figi:
3093                            instrument = item
3094                            break
3095
3096                if instrument:
3097                    self._ticker = instrument["ticker"]
3098                    self._figi = instrument["figi"]
3099
3100                    uLogger.debug("Closing trade of instrument: ticker [{}], FIGI[{}], lots [{}]{}. Wait, please...".format(
3101                        self._ticker,
3102                        self._figi,
3103                        int(instrument["volume"]),
3104                        ", blocked [{}]".format(instrument["blocked"]) if instrument["blocked"] > 0 else "",
3105                    ))
3106
3107                    tradeLots = abs(instrument["lots"]) - instrument["blocked"]  # available volumes in lots for close operation
3108
3109                    if tradeLots > 0:
3110                        if instrument["blocked"] > 0:
3111                            uLogger.warning("Just for your information: there are [{}] lots blocked for instrument [{}]! Available only [{}] lots to closing trade.".format(
3112                                instrument["blocked"],
3113                                self._ticker,
3114                                tradeLots,
3115                            ))
3116
3117                        # if direction is "Long" then we need sell, if direction is "Short" then we need buy:
3118                        self.Trade(operation="Sell" if instrument["direction"] == "Long" else "Buy", lots=tradeLots)
3119
3120                    else:
3121                        uLogger.warning("There are no available lots for instrument [{}] to closing trade at this moment! Try again later or cancel some orders.".format(self._ticker))
3122
3123    def CloseAllTrades(self, iType: str, portfolio: dict = None) -> None:
3124        """
3125        Close all positions of given instruments with defined type.
3126
3127        :param iType: type of the instruments that be closed, it must be one of supported types in TKS_INSTRUMENTS list.
3128        :param portfolio: pre-received dictionary with open trades, returned by `Overview()` method.
3129                         This avoids unnecessary downloading data from the server.
3130        """
3131        if iType not in TKS_INSTRUMENTS:
3132            uLogger.warning("Type of the instrument must be one of supported types: {}. Given: [{}]".format(", ".join(TKS_INSTRUMENTS), iType))
3133
3134        else:
3135            if portfolio is None or not portfolio:
3136                portfolio = self.Overview(show=False)
3137
3138            tickers = [item["ticker"] for item in portfolio["stat"][iType]]
3139            uLogger.debug("Instrument tickers with type [{}] that will be closed: {}".format(iType, tickers))
3140
3141            if tickers and portfolio:
3142                self.CloseTrades(tickers, portfolio)
3143
3144            else:
3145                uLogger.info("Instrument tickers with type [{}] not found, nothing to close.".format(iType))
3146
3147    def Order(self, operation: str, orderType: str, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3148        """
3149        Universal method to create market or limit orders with all available parameters for current `accountId`.
3150        See more simple methods: `BuyLimit()`, `BuyStop()`, `SellLimit()`, `SellStop()`.
3151
3152        If orderType is "Limit" then create pending limit-order below current price if operation is "Buy" and above
3153        current price if operation is "Sell". A limit order has no expiration date, it lasts until the end of the trading day.
3154
3155        Warning! If you try to create limit-order above current price if "Buy" or below current price if "Sell"
3156        then broker immediately open market order as you can do simple --buy or --sell operations!
3157
3158        If orderType is "Stop" then creates stop-order with any direction "Buy" or "Sell".
3159        When current price will go up or down to target price value then broker opens a limit order.
3160        Stop-order is opened with unlimited expiration date by default, or you can define expiration date with expDate parameter.
3161
3162        Only one attempt and no retry for opens order. If network issue occurred you can create new request.
3163
3164        :param operation: string "Buy" or "Sell".
3165        :param orderType: string "Limit" or "Stop".
3166        :param lots: volume, integer count of lots >= 1.
3167        :param targetPrice: target price > 0. This is open trade price for limit order.
3168        :param limitPrice: limit price >= 0. This parameter only makes sense for stop-order. If limitPrice = 0, then it set as targetPrice.
3169                           Broker will creates limit-order with price equal to limitPrice, when current price goes to target price of stop-order.
3170        :param stopType: string "Limit" by default. This parameter only makes sense for stop-order. There are 3 stop-order types
3171                         "SL", "TP", "Limit" for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3172                         Stop loss order always executed by market price.
3173        :param expDate: string "Undefined" by default or local date in future.
3174                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3175                        This date is converting to UTC format for server. This parameter only makes sense for stop-order.
3176                        A limit order has no expiration date, it lasts until the end of the trading day.
3177        :return: JSON with response from broker server.
3178        """
3179        if self.accountId is None or not self.accountId:
3180            uLogger.error("Variable `accountId` must be defined for using this method!")
3181            raise Exception("Account ID required")
3182
3183        if operation is None or not operation or operation not in ("Buy", "Sell"):
3184            uLogger.error("You must define operation type only one of them: `Buy` or `Sell`!")
3185            raise Exception("Incorrect value")
3186
3187        if orderType is None or not orderType or orderType not in ("Limit", "Stop"):
3188            uLogger.error("You must define order type only one of them: `Limit` or `Stop`!")
3189            raise Exception("Incorrect value")
3190
3191        if lots is None or lots < 1:
3192            uLogger.error("You must define trade volume > 0: integer count of lots!")
3193            raise Exception("Incorrect value")
3194
3195        if targetPrice is None or targetPrice <= 0:
3196            uLogger.error("Target price for limit-order must be greater than 0!")
3197            raise Exception("Incorrect value")
3198
3199        if limitPrice is None or limitPrice <= 0:
3200            limitPrice = targetPrice
3201
3202        if stopType is None or not stopType or stopType not in ("SL", "TP", "Limit"):
3203            stopType = "Limit"
3204
3205        if expDate is None or not expDate:
3206            expDate = "Undefined"
3207
3208        if not (self._ticker or self._figi):
3209            uLogger.error("Tocker or FIGI must be defined!")
3210            raise Exception("Ticker or FIGI required")
3211
3212        response = {}
3213        instrument = self.SearchByTicker(requestPrice=True) if self._ticker else self.SearchByFIGI(requestPrice=True)
3214        self._ticker = instrument["ticker"]
3215        self._figi = instrument["figi"]
3216
3217        if orderType == "Limit":
3218            uLogger.debug(
3219                "Creating pending limit-order: ticker [{}], FIGI [{}], action [{}], lots [{}] and the target price [{:.2f} {}]. Wait, please...".format(
3220                    self._ticker, self._figi,
3221                    operation, lots, targetPrice, instrument["currency"],
3222                ))
3223
3224            openOrderURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/PostOrder"
3225            self.body = str({
3226                "figi": self._figi,
3227                "quantity": str(lots),
3228                "price": FloatToNano(targetPrice),
3229                "direction": "ORDER_DIRECTION_BUY" if operation == "Buy" else "ORDER_DIRECTION_SELL",  # see: TKS_ORDER_DIRECTIONS
3230                "accountId": str(self.accountId),
3231                "orderType": "ORDER_TYPE_LIMIT",  # see: TKS_ORDER_TYPES
3232            })
3233            response = self.SendAPIRequest(openOrderURL, reqType="POST", retry=0)
3234
3235            if "orderId" in response.keys():
3236                uLogger.info(
3237                    "Limit-order [{}] was created: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{} {}]".format(
3238                        response["orderId"], self._ticker, self._figi, operation, lots,
3239                        "{:.4f}".format(targetPrice).rstrip("0").rstrip("."), instrument["currency"],
3240                    ))
3241
3242                if "lastPrice" in instrument["currentPrice"].keys() and instrument["currentPrice"]["lastPrice"]:
3243                    if operation == "Buy" and targetPrice > instrument["currentPrice"]["lastPrice"]:
3244                        uLogger.warning("Your order was executed as a market order, not as a limit order! Comment: because your target price [{:.2f} {}] was higher than current price [{:.2f} {}] broker immediately opened `Buy` market order, such as if you did simple `--buy` operation.".format(
3245                            targetPrice, instrument["currency"],
3246                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3247                        ))
3248
3249                    if operation == "Sell" and targetPrice < instrument["currentPrice"]["lastPrice"]:
3250                        uLogger.warning("Your order was executed as a market order, not as a limit order! Comment: because your target price [{:.2f} {}] was lower than current price [{:.2f} {}] broker immediately opened `Sell` market order, such as if you did simple `--sell` operation.".format(
3251                            targetPrice, instrument["currency"],
3252                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3253                        ))
3254
3255            else:
3256                uLogger.warning("Not `oK` status received! Limit order not opened. See full debug log and try again open order later.")
3257
3258        if orderType == "Stop":
3259            uLogger.debug(
3260                "Creating stop-order: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{:.2f} {}], limit price [{:.2f} {}], stop-order type [{}] and local expiration date [{}]. Wait, please...".format(
3261                    self._ticker, self._figi,
3262                    operation, lots,
3263                    targetPrice, instrument["currency"],
3264                    limitPrice, instrument["currency"],
3265                    stopType, expDate,
3266                ))
3267
3268            openOrderURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/PostStopOrder"
3269            expDateUTC = "" if expDate == "Undefined" else datetime.strptime(expDate, TKS_PRINT_DATE_TIME_FORMAT).replace(tzinfo=tzlocal()).astimezone(tzutc()).strftime(TKS_DATE_TIME_FORMAT_EXT)
3270            stopOrderType = "STOP_ORDER_TYPE_STOP_LOSS" if stopType == "SL" else "STOP_ORDER_TYPE_TAKE_PROFIT" if stopType == "TP" else "STOP_ORDER_TYPE_STOP_LIMIT"
3271
3272            body = {
3273                "figi": self._figi,
3274                "quantity": str(lots),
3275                "price": FloatToNano(limitPrice),
3276                "stopPrice": FloatToNano(targetPrice),
3277                "direction": "STOP_ORDER_DIRECTION_BUY" if operation == "Buy" else "STOP_ORDER_DIRECTION_SELL",  # see: TKS_STOP_ORDER_DIRECTIONS
3278                "accountId": str(self.accountId),
3279                "expirationType": "STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_DATE" if expDateUTC else "STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_CANCEL",  # see: TKS_STOP_ORDER_EXPIRATION_TYPES
3280                "stopOrderType": stopOrderType,  # see: TKS_STOP_ORDER_TYPES
3281            }
3282
3283            if expDateUTC:
3284                body["expireDate"] = expDateUTC
3285
3286            self.body = str(body)
3287            response = self.SendAPIRequest(openOrderURL, reqType="POST", retry=0)
3288
3289            if "stopOrderId" in response.keys():
3290                uLogger.info(
3291                    "Stop-order [{}] was created: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{} {}], limit price [{} {}], stop-order type [{}] and expiration date [{} UTC]".format(
3292                        response["stopOrderId"], self._ticker, self._figi, operation, lots,
3293                        "{:.4f}".format(targetPrice).rstrip("0").rstrip("."), instrument["currency"],
3294                        "{:.4f}".format(limitPrice).rstrip("0").rstrip("."), instrument["currency"],
3295                        TKS_STOP_ORDER_TYPES[stopOrderType],
3296                        datetime.strptime(expDateUTC, TKS_DATE_TIME_FORMAT_EXT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT) if expDateUTC else TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_UNSPECIFIED"],
3297                    ))
3298
3299                if "lastPrice" in instrument["currentPrice"].keys() and instrument["currentPrice"]["lastPrice"]:
3300                    if operation == "Buy" and targetPrice < instrument["currentPrice"]["lastPrice"] and stopType != "TP":
3301                        uLogger.warning("The broker will cancel this order after some time. Comment: you placed the wrong stop order because the target buy price [{:.2f} {}] is lower than the current price [{:.2f} {}]. Also try to set up order type as `TP` if you want to place stop order at that price.".format(
3302                            targetPrice, instrument["currency"],
3303                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3304                        ))
3305
3306                    if operation == "Sell" and targetPrice > instrument["currentPrice"]["lastPrice"] and stopType != "TP":
3307                        uLogger.warning("The broker will cancel this order after some time. Comment: you placed the wrong stop order because the target sell price [{:.2f} {}] is higher than the current price [{:.2f} {}]. Also try to set up order type as `TP` if you want to place stop order at that price.".format(
3308                            targetPrice, instrument["currency"],
3309                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3310                        ))
3311
3312            else:
3313                uLogger.warning("Not `oK` status received! Stop order not opened. See full debug log and try again open order later.")
3314
3315        return response
3316
3317    def BuyLimit(self, lots: int, targetPrice: float) -> dict:
3318        """
3319        Create pending `Buy` limit-order (below current price). You must specify only 2 parameters:
3320        `lots` and `target price` to open buy limit-order. If you try to create buy limit-order above current price then
3321        broker immediately open `Buy` market order, such as if you do simple `--buy` operation!
3322        See also: `Order()` docstring.
3323
3324        :param lots: volume, integer count of lots >= 1.
3325        :param targetPrice: target price > 0. This is open trade price for limit order.
3326        :return: JSON with response from broker server.
3327        """
3328        return self.Order(operation="Buy", orderType="Limit", lots=lots, targetPrice=targetPrice)
3329
3330    def BuyStop(self, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3331        """
3332        Create `Buy` stop-order. You must specify at least 2 parameters: `lots` `target price` to open buy stop-order.
3333        In additional you can specify 3 parameters for buy stop-order: `limit price` >=0, `stop type` = Limit|SL|TP,
3334        `expiration date` = Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`. When current price will go up or down to
3335        target price value then broker opens a limit order. See also: `Order()` docstring.
3336
3337        :param lots: volume, integer count of lots >= 1.
3338        :param targetPrice: target price > 0. This is trigger price for buy stop-order.
3339        :param limitPrice: limit price >= 0 (limitPrice = targetPrice if limitPrice is 0). Broker will creates limit-order
3340                           with price equal to limitPrice, when current price goes to target price of buy stop-order.
3341        :param stopType: string "Limit" by default. There are 3 stop-order types "SL", "TP", "Limit"
3342                         for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3343        :param expDate: string "Undefined" by default or local date in future.
3344                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3345                        This date is converting to UTC format for server.
3346        :return: JSON with response from broker server.
3347        """
3348        return self.Order(operation="Buy", orderType="Stop", lots=lots, targetPrice=targetPrice, limitPrice=limitPrice, stopType=stopType, expDate=expDate)
3349
3350    def SellLimit(self, lots: int, targetPrice: float) -> dict:
3351        """
3352        Create pending `Sell` limit-order (above current price). You must specify only 2 parameters:
3353        `lots` and `target price` to open sell limit-order. If you try to create sell limit-order below current price then
3354        broker immediately open `Sell` market order, such as if you do simple `--sell` operation!
3355        See also: `Order()` docstring.
3356
3357        :param lots: volume, integer count of lots >= 1.
3358        :param targetPrice: target price > 0. This is open trade price for limit order.
3359        :return: JSON with response from broker server.
3360        """
3361        return self.Order(operation="Sell", orderType="Limit", lots=lots, targetPrice=targetPrice)
3362
3363    def SellStop(self, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3364        """
3365        Create `Sell` stop-order. You must specify at least 2 parameters: `lots` `target price` to open sell stop-order.
3366        In additional you can specify 3 parameters for sell stop-order: `limit price` >=0, `stop type` = Limit|SL|TP,
3367        `expiration date` = Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`. When current price will go up or down to
3368        target price value then broker opens a limit order. See also: `Order()` docstring.
3369
3370        :param lots: volume, integer count of lots >= 1.
3371        :param targetPrice: target price > 0. This is trigger price for sell stop-order.
3372        :param limitPrice: limit price >= 0 (limitPrice = targetPrice if limitPrice is 0). Broker will creates limit-order
3373                           with price equal to limitPrice, when current price goes to target price of sell stop-order.
3374        :param stopType: string "Limit" by default. There are 3 stop-order types "SL", "TP", "Limit"
3375                         for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3376        :param expDate: string "Undefined" by default or local date in future.
3377                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3378                        This date is converting to UTC format for server.
3379        :return: JSON with response from broker server.
3380        """
3381        return self.Order(operation="Sell", orderType="Stop", lots=lots, targetPrice=targetPrice, limitPrice=limitPrice, stopType=stopType, expDate=expDate)
3382
3383    def CloseOrders(self, orderIDs: list, allOrdersIDs: list = None, allStopOrdersIDs: list = None) -> None:
3384        """
3385        Cancel order or list of orders by its `orderId` or `stopOrderId` for current `accountId`.
3386
3387        :param orderIDs: list of integers with `orderId` or `stopOrderId`.
3388        :param allOrdersIDs: pre-received lists of all active pending limit orders.
3389                             This avoids unnecessary downloading data from the server.
3390        :param allStopOrdersIDs: pre-received lists of all active stop orders.
3391        """
3392        if self.accountId is None or not self.accountId:
3393            uLogger.error("Variable `accountId` must be defined for using this method!")
3394            raise Exception("Account ID required")
3395
3396        if orderIDs:
3397            if allOrdersIDs is None:
3398                rawOrders = self.RequestPendingOrders()
3399                allOrdersIDs = [item["orderId"] for item in rawOrders]  # all pending limit orders ID
3400
3401            if allStopOrdersIDs is None:
3402                rawStopOrders = self.RequestStopOrders()
3403                allStopOrdersIDs = [item["stopOrderId"] for item in rawStopOrders]  # all stop orders ID
3404
3405            for orderID in orderIDs:
3406                idInPendingOrders = orderID in allOrdersIDs
3407                idInStopOrders = orderID in allStopOrdersIDs
3408
3409                if not (idInPendingOrders or idInStopOrders):
3410                    uLogger.warning("Order not found by ID: [{}]. Maybe cancelled already? Check it with `--overview` key.".format(orderID))
3411                    continue
3412
3413                else:
3414                    if idInPendingOrders:
3415                        uLogger.debug("Cancelling pending order with ID: [{}]. Wait, please...".format(orderID))
3416
3417                        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/OrdersService/OrdersService_CancelOrder
3418                        self.body = str({"accountId": self.accountId, "orderId": orderID})
3419                        closeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/CancelOrder"
3420                        responseJSON = self.SendAPIRequest(closeURL, reqType="POST")
3421
3422                        if responseJSON and "time" in responseJSON.keys() and responseJSON["time"]:
3423                            if self.moreDebug:
3424                                uLogger.debug("Success time marker received from server: [{}] (UTC)".format(responseJSON["time"]))
3425
3426                            uLogger.info("Pending order with ID [{}] successfully cancel".format(orderID))
3427
3428                        else:
3429                            uLogger.warning("Unknown issue occurred when cancelling pending order with ID: [{}]. Check ID and try again.".format(orderID))
3430
3431                    elif idInStopOrders:
3432                        uLogger.debug("Cancelling stop order with ID: [{}]. Wait, please...".format(orderID))
3433
3434                        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/StopOrdersService/StopOrdersService_CancelStopOrder
3435                        self.body = str({"accountId": self.accountId, "stopOrderId": orderID})
3436                        closeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/CancelStopOrder"
3437                        responseJSON = self.SendAPIRequest(closeURL, reqType="POST")
3438
3439                        if responseJSON and "time" in responseJSON.keys() and responseJSON["time"]:
3440                            if self.moreDebug:
3441                                uLogger.debug("Success time marker received from server: [{}] (UTC)".format(responseJSON["time"]))
3442
3443                            uLogger.info("Stop order with ID [{}] successfully cancel".format(orderID))
3444
3445                        else:
3446                            uLogger.warning("Unknown issue occurred when cancelling stop order with ID: [{}]. Check ID and try again.".format(orderID))
3447
3448                    else:
3449                        continue
3450
3451    def CloseAllOrders(self) -> None:
3452        """
3453        Gets a list of open pending and stop orders and cancel it all.
3454        """
3455        rawOrders = self.RequestPendingOrders()
3456        allOrdersIDs = [item["orderId"] for item in rawOrders]  # all pending limit orders ID
3457        lenOrders = len(allOrdersIDs)
3458
3459        rawStopOrders = self.RequestStopOrders()
3460        allStopOrdersIDs = [item["stopOrderId"] for item in rawStopOrders]  # all stop orders ID
3461        lenSOrders = len(allStopOrdersIDs)
3462
3463        if lenOrders > 0 or lenSOrders > 0:
3464            uLogger.info("Found: [{}] opened pending and [{}] stop orders. Let's trying to cancel it all. Wait, please...".format(lenOrders, lenSOrders))
3465
3466            self.CloseOrders(allOrdersIDs + allStopOrdersIDs, allOrdersIDs, allStopOrdersIDs)
3467
3468        else:
3469            uLogger.info("Orders not found, nothing to cancel.")
3470
3471    def CloseAll(self, *args) -> None:
3472        """
3473        Close all available (not blocked) opened trades and orders.
3474
3475        Also, you can select one or more keywords case-insensitive:
3476        `orders`, `shares`, `bonds`, `etfs` and `futures` from `TKS_INSTRUMENTS` enum to specify trades type.
3477
3478        Currency positions you must close manually using buy or sell operations, `CloseTrades()` or `CloseAllTrades()` methods.
3479        """
3480        overview = self.Overview(show=False)  # get all open trades info
3481
3482        if len(args) == 0:
3483            uLogger.debug("Closing all available (not blocked) opened trades and orders. Currency positions you must closes manually using buy or sell operations! Wait, please...")
3484            self.CloseAllOrders()  # close all pending and stop orders
3485
3486            for iType in TKS_INSTRUMENTS:
3487                if iType != "Currencies":
3488                    self.CloseAllTrades(iType, overview)  # close all positions of instruments with same type without currencies
3489
3490        else:
3491            uLogger.debug("Closing all available {}. Currency positions you must closes manually using buy or sell operations! Wait, please...".format(list(args)))
3492            lowerArgs = [x.lower() for x in args]
3493
3494            if "orders" in lowerArgs:
3495                self.CloseAllOrders()  # close all pending and stop orders
3496
3497            for iType in TKS_INSTRUMENTS:
3498                if iType.lower() in lowerArgs and iType != "Currencies":
3499                    self.CloseAllTrades(iType, overview)  # close all positions of instruments with same type without currencies
3500
3501    def CloseAllByTicker(self, instrument: str) -> None:
3502        """
3503        Close all available (not blocked) opened trades and orders for one instrument defined by its ticker.
3504
3505        This method searches opened trade and orders of instrument throw all portfolio and then use
3506        `CloseTrades()` and `CloseOrders()` methods to close trade and cancel all orders for that instrument.
3507
3508        See also: `IsInLimitOrders()`, `GetLimitOrderIDs()`, `IsInStopOrders()`, `GetStopOrderIDs()`, `CloseTrades()` and `CloseOrders()`.
3509
3510        :param instrument: string with ticker.
3511        """
3512        if instrument is None or not instrument:
3513            uLogger.error("Ticker name must be defined for using this method!")
3514            raise Exception("Ticker required")
3515
3516        overview = self.Overview(show=False)  # get user portfolio with all open trades info
3517
3518        self._ticker = instrument  # try to set instrument as ticker
3519        self._figi = ""
3520
3521        limitAll = [item["orderID"] for item in overview["stat"]["orders"]]  # list of all pending limit order IDs
3522        stopAll = [item["orderID"] for item in overview["stat"]["stopOrders"]]  # list of all stop order IDs
3523
3524        if limitAll and self.IsInLimitOrders(portfolio=overview):
3525            uLogger.debug("Closing all opened pending limit orders for the instrument with ticker [{}]. Wait, please...")
3526            self.CloseOrders(orderIDs=self.GetLimitOrderIDs(portfolio=overview), allOrdersIDs=limitAll, allStopOrdersIDs=stopAll)
3527
3528        if stopAll and self.IsInStopOrders(portfolio=overview):
3529            uLogger.debug("Closing all opened stop orders for the instrument with ticker [{}]. Wait, please...")
3530            self.CloseOrders(orderIDs=self.GetStopOrderIDs(portfolio=overview), allOrdersIDs=limitAll, allStopOrdersIDs=stopAll)
3531
3532        if self.IsInPortfolio(portfolio=overview):
3533            uLogger.debug("Closing all available (not blocked) opened trade for the instrument with ticker [{}]. Wait, please...")
3534            self.CloseTrades(instruments=[instrument], portfolio=overview)
3535
3536    def CloseAllByFIGI(self, instrument: str) -> None:
3537        """
3538        Close all available (not blocked) opened trades and orders for one instrument defined by its FIGI id.
3539
3540        This method searches opened trade and orders of instrument throw all portfolio and then use
3541        `CloseTrades()` and `CloseOrders()` methods to close trade and cancel all orders for that instrument.
3542
3543        See also: `IsInLimitOrders()`, `GetLimitOrderIDs()`, `IsInStopOrders()`, `GetStopOrderIDs()`, `CloseTrades()` and `CloseOrders()`.
3544
3545        :param instrument: string with FIGI id.
3546        """
3547        if instrument is None or not instrument:
3548            uLogger.error("FIGI id must be defined for using this method!")
3549            raise Exception("FIGI required")
3550
3551        overview = self.Overview(show=False)  # get user portfolio with all open trades info
3552
3553        self._ticker = ""
3554        self._figi = instrument  # try to set instrument as FIGI id
3555
3556        limitAll = [item["orderID"] for item in overview["stat"]["orders"]]  # list of all pending limit order IDs
3557        stopAll = [item["orderID"] for item in overview["stat"]["stopOrders"]]  # list of all stop order IDs
3558
3559        if limitAll and self.IsInLimitOrders(portfolio=overview):
3560            uLogger.debug("Closing all opened pending limit orders for the instrument with FIGI [{}]. Wait, please...")
3561            self.CloseOrders(orderIDs=self.GetLimitOrderIDs(portfolio=overview), allOrdersIDs=limitAll, allStopOrdersIDs=stopAll)
3562
3563        if stopAll and self.IsInStopOrders(portfolio=overview):
3564            uLogger.debug("Closing all opened stop orders for the instrument with FIGI [{}]. Wait, please...")
3565            self.CloseOrders(orderIDs=self.GetStopOrderIDs(portfolio=overview), allOrdersIDs=limitAll, allStopOrdersIDs=stopAll)
3566
3567        if self.IsInPortfolio(portfolio=overview):
3568            uLogger.debug("Closing all available (not blocked) opened trade for the instrument with FIGI [{}]. Wait, please...")
3569            self.CloseTrades(instruments=[instrument], portfolio=overview)
3570
3571    @staticmethod
3572    def ParseOrderParameters(operation, **inputParameters):
3573        """
3574        Parse input dictionary of strings with order parameters and return dictionary with parameters to open all orders.
3575
3576        :param operation: string "Buy" or "Sell".
3577        :param inputParameters: this is dict of strings that looks like this
3578               `{"lots": "L_int,...", "prices": "P_float,..."}` where
3579               "lots" key: one or more lot values (integer numbers) to open with every limit-order
3580               "prices" key: one or more prices to open limit-orders
3581               Counts of values in lots and prices lists must be equals!
3582        :return: list of dictionaries with all lots and prices to open orders that looks like this `[{"lot": lots_1, "price": price_1}, {...}, ...]`
3583        """
3584        # TODO: update order grid work with api v2
3585        pass
3586        # uLogger.debug("Input parameters: {}".format(inputParameters))
3587        #
3588        # if operation is None or not operation or operation not in ("Buy", "Sell"):
3589        #     uLogger.error("You must define operation type: 'Buy' or 'Sell'!")
3590        #     raise Exception("Incorrect value")
3591        #
3592        # if "l" in inputParameters.keys():
3593        #     inputParameters["lots"] = inputParameters.pop("l")
3594        #
3595        # if "p" in inputParameters.keys():
3596        #     inputParameters["prices"] = inputParameters.pop("p")
3597        #
3598        # if "lots" not in inputParameters.keys() or "prices" not in inputParameters.keys():
3599        #     uLogger.error("Both of 'lots' and 'prices' keys must be define to open grid orders!")
3600        #     raise Exception("Incorrect value")
3601        #
3602        # lots = [int(item.strip()) for item in inputParameters["lots"].split(",")]
3603        # prices = [float(item.strip()) for item in inputParameters["prices"].split(",")]
3604        #
3605        # if len(lots) != len(prices):
3606        #     uLogger.error("'lots' and 'prices' lists must have equal length of values!")
3607        #     raise Exception("Incorrect value")
3608        #
3609        # uLogger.debug("Extracted parameters for orders:")
3610        # uLogger.debug("lots = {}".format(lots))
3611        # uLogger.debug("prices = {}".format(prices))
3612        #
3613        # # list of dictionaries with order's parameters: [{"lot": lots_1, "price": price_1}, {...}, ...]
3614        # result = [{"lot": lots[item], "price": prices[item]} for item in range(len(prices))]
3615        # uLogger.debug("Order parameters: {}".format(result))
3616        #
3617        # return result
3618
3619    def IsInPortfolio(self, portfolio: dict = None) -> bool:
3620        """
3621        Checks if instrument is in the user's portfolio. Instrument must be defined by `ticker` (highly priority) or `figi`.
3622
3623        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3624        :return: `True` if portfolio contains open position with given instrument, `False` otherwise.
3625        """
3626        result = False
3627        msg = "Instrument not defined!"
3628
3629        if portfolio is None or not portfolio:
3630            portfolio = self.Overview(show=False)
3631
3632        if self._ticker:
3633            uLogger.debug("Searching instrument with ticker [{}] throw opened positions list...".format(self._ticker))
3634            msg = "Instrument with ticker [{}] is not present in open positions".format(self._ticker)
3635
3636            for iType in TKS_INSTRUMENTS:
3637                for instrument in portfolio["stat"][iType]:
3638                    if instrument["ticker"] == self._ticker:
3639                        result = True
3640                        msg = "Instrument with ticker [{}] is present in open positions".format(self._ticker)
3641                        break
3642
3643        elif self._figi:
3644            uLogger.debug("Searching instrument with FIGI [{}] throw opened positions list...".format(self._figi))
3645            msg = "Instrument with FIGI [{}] is not present in open positions".format(self._figi)
3646
3647            for iType in TKS_INSTRUMENTS:
3648                for instrument in portfolio["stat"][iType]:
3649                    if instrument["figi"] == self._figi:
3650                        result = True
3651                        msg = "Instrument with FIGI [{}] is present in open positions".format(self._figi)
3652                        break
3653
3654        else:
3655            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3656
3657        uLogger.debug(msg)
3658
3659        return result
3660
3661    def GetInstrumentFromPortfolio(self, portfolio: dict = None) -> dict:
3662        """
3663        Returns instrument from the user's portfolio if it presents there.
3664        Instrument must be defined by `ticker` (highly priority) or `figi`.
3665
3666        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3667        :return: dict with instrument if portfolio contains open position with this instrument, `None` otherwise.
3668        """
3669        result = None
3670        msg = "Instrument not defined!"
3671
3672        if portfolio is None or not portfolio:
3673            portfolio = self.Overview(show=False)
3674
3675        if self._ticker:
3676            uLogger.debug("Searching instrument with ticker [{}] in opened positions...".format(self._ticker))
3677            msg = "Instrument with ticker [{}] is not present in open positions".format(self._ticker)
3678
3679            for iType in TKS_INSTRUMENTS:
3680                for instrument in portfolio["stat"][iType]:
3681                    if instrument["ticker"] == self._ticker:
3682                        result = instrument
3683                        msg = "Instrument with ticker [{}] and FIGI [{}] is present in open positions".format(self._ticker, instrument["figi"])
3684                        break
3685
3686        elif self._figi:
3687            uLogger.debug("Searching instrument with FIGI [{}] throwout opened positions...".format(self._figi))
3688            msg = "Instrument with FIGI [{}] is not present in open positions".format(self._figi)
3689
3690            for iType in TKS_INSTRUMENTS:
3691                for instrument in portfolio["stat"][iType]:
3692                    if instrument["figi"] == self._figi:
3693                        result = instrument
3694                        msg = "Instrument with ticker [{}] and FIGI [{}] is present in open positions".format(instrument["ticker"], self._figi)
3695                        break
3696
3697        else:
3698            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3699
3700        uLogger.debug(msg)
3701
3702        return result
3703
3704    def IsInLimitOrders(self, portfolio: dict = None) -> bool:
3705        """
3706        Checks if instrument is in the limit orders list. Instrument must be defined by `ticker` (highly priority) or `figi`.
3707
3708        See also: `CloseAllByTicker()` and `CloseAllByFIGI()`.
3709
3710        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3711        :return: `True` if limit orders list contains some limit orders for the instrument, `False` otherwise.
3712        """
3713        result = False
3714        msg = "Instrument not defined!"
3715
3716        if portfolio is None or not portfolio:
3717            portfolio = self.Overview(show=False)
3718
3719        if self._ticker:
3720            uLogger.debug("Searching instrument with ticker [{}] throw opened pending limit orders list...".format(self._ticker))
3721            msg = "Instrument with ticker [{}] is not present in opened pending limit orders list".format(self._ticker)
3722
3723            for instrument in portfolio["stat"]["orders"]:
3724                if instrument["ticker"] == self._ticker:
3725                    result = True
3726                    msg = "Instrument with ticker [{}] is present in limit orders list".format(self._ticker)
3727                    break
3728
3729        elif self._figi:
3730            uLogger.debug("Searching instrument with FIGI [{}] throw opened pending limit orders list...".format(self._figi))
3731            msg = "Instrument with FIGI [{}] is not present in opened pending limit orders list".format(self._figi)
3732
3733            for instrument in portfolio["stat"]["orders"]:
3734                if instrument["figi"] == self._figi:
3735                    result = True
3736                    msg = "Instrument with FIGI [{}] is present in opened pending limit orders list".format(self._figi)
3737                    break
3738
3739        else:
3740            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3741
3742        uLogger.debug(msg)
3743
3744        return result
3745
3746    def GetLimitOrderIDs(self, portfolio: dict = None) -> list[str]:
3747        """
3748        Returns list with all `orderID`s of opened pending limit orders for the instrument.
3749        Instrument must be defined by `ticker` (highly priority) or `figi`.
3750
3751        See also: `CloseAllByTicker()` and `CloseAllByFIGI()`.
3752
3753        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3754        :return: list with `orderID`s of limit orders.
3755        """
3756        result = []
3757        msg = "Instrument not defined!"
3758
3759        if portfolio is None or not portfolio:
3760            portfolio = self.Overview(show=False)
3761
3762        if self._ticker:
3763            uLogger.debug("Searching instrument with ticker [{}] throw opened pending limit orders list...".format(self._ticker))
3764            msg = "Instrument with ticker [{}] is not present in opened pending limit orders list".format(self._ticker)
3765
3766            for instrument in portfolio["stat"]["orders"]:
3767                if instrument["ticker"] == self._ticker:
3768                    result.append(instrument["orderID"])
3769
3770            if result:
3771                msg = "Instrument with ticker [{}] is present in limit orders list".format(self._ticker)
3772
3773        elif self._figi:
3774            uLogger.debug("Searching instrument with FIGI [{}] throw opened pending limit orders list...".format(self._figi))
3775            msg = "Instrument with FIGI [{}] is not present in opened pending limit orders list".format(self._figi)
3776
3777            for instrument in portfolio["stat"]["orders"]:
3778                if instrument["figi"] == self._figi:
3779                    result.append(instrument["orderID"])
3780
3781            if result:
3782                msg = "Instrument with FIGI [{}] is present in opened pending limit orders list".format(self._figi)
3783
3784        else:
3785            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3786
3787        uLogger.debug(msg)
3788
3789        return result
3790
3791    def IsInStopOrders(self, portfolio: dict = None) -> bool:
3792        """
3793        Checks if instrument is in the stop orders list. Instrument must be defined by `ticker` (highly priority) or `figi`.
3794
3795        See also: `CloseAllByTicker()` and `CloseAllByFIGI()`.
3796
3797        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3798        :return: `True` if stop orders list contains some stop orders for the instrument, `False` otherwise.
3799        """
3800        result = False
3801        msg = "Instrument not defined!"
3802
3803        if portfolio is None or not portfolio:
3804            portfolio = self.Overview(show=False)
3805
3806        if self._ticker:
3807            uLogger.debug("Searching instrument with ticker [{}] throw opened stop orders list...".format(self._ticker))
3808            msg = "Instrument with ticker [{}] is not present in opened stop orders list".format(self._ticker)
3809
3810            for instrument in portfolio["stat"]["stopOrders"]:
3811                if instrument["ticker"] == self._ticker:
3812                    result = True
3813                    msg = "Instrument with ticker [{}] is present in stop orders list".format(self._ticker)
3814                    break
3815
3816        elif self._figi:
3817            uLogger.debug("Searching instrument with FIGI [{}] throw opened stop orders list...".format(self._figi))
3818            msg = "Instrument with FIGI [{}] is not present in opened stop orders list".format(self._figi)
3819
3820            for instrument in portfolio["stat"]["stopOrders"]:
3821                if instrument["figi"] == self._figi:
3822                    result = True
3823                    msg = "Instrument with FIGI [{}] is present in opened stop orders list".format(self._figi)
3824                    break
3825
3826        else:
3827            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3828
3829        uLogger.debug(msg)
3830
3831        return result
3832
3833    def GetStopOrderIDs(self, portfolio: dict = None) -> list[str]:
3834        """
3835        Returns list with all `orderID`s of opened stop orders for the instrument.
3836        Instrument must be defined by `ticker` (highly priority) or `figi`.
3837
3838        See also: `CloseAllByTicker()` and `CloseAllByFIGI()`.
3839
3840        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3841        :return: list with `orderID`s of stop orders.
3842        """
3843        result = []
3844        msg = "Instrument not defined!"
3845
3846        if portfolio is None or not portfolio:
3847            portfolio = self.Overview(show=False)
3848
3849        if self._ticker:
3850            uLogger.debug("Searching instrument with ticker [{}] throw opened stop orders list...".format(self._ticker))
3851            msg = "Instrument with ticker [{}] is not present in opened stop orders list".format(self._ticker)
3852
3853            for instrument in portfolio["stat"]["stopOrders"]:
3854                if instrument["ticker"] == self._ticker:
3855                    result.append(instrument["orderID"])
3856
3857            if result:
3858                msg = "Instrument with ticker [{}] is present in stop orders list".format(self._ticker)
3859
3860        elif self._figi:
3861            uLogger.debug("Searching instrument with FIGI [{}] throw opened stop orders list...".format(self._figi))
3862            msg = "Instrument with FIGI [{}] is not present in opened stop orders list".format(self._figi)
3863
3864            for instrument in portfolio["stat"]["stopOrders"]:
3865                if instrument["figi"] == self._figi:
3866                    result.append(instrument["orderID"])
3867
3868            if result:
3869                msg = "Instrument with FIGI [{}] is present in opened stop orders list".format(self._figi)
3870
3871        else:
3872            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3873
3874        uLogger.debug(msg)
3875
3876        return result
3877
3878    def RequestLimits(self) -> dict:
3879        """
3880        Method for obtaining the available funds for withdrawal for current `accountId`.
3881
3882        See also:
3883        - REST API for limits: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetWithdrawLimits
3884        - `OverviewLimits()` method
3885
3886        :return: dict with raw data from server that contains free funds for withdrawal. Example of dict:
3887                 `{"money": [{"currency": "rub", "units": "100", "nano": 290000000}, {...}], "blocked": [...], "blockedGuarantee": [...]}`.
3888                 Here `money` is an array of portfolio currency positions, `blocked` is an array of blocked currency
3889                 positions of the portfolio and `blockedGuarantee` is locked money under collateral for futures.
3890        """
3891        if self.accountId is None or not self.accountId:
3892            uLogger.error("Variable `accountId` must be defined for using this method!")
3893            raise Exception("Account ID required")
3894
3895        uLogger.debug("Requesting current available funds for withdrawal. Wait, please...")
3896
3897        self.body = str({"accountId": self.accountId})
3898        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetWithdrawLimits"
3899        rawLimits = self.SendAPIRequest(portfolioURL, reqType="POST")
3900
3901        if self.moreDebug:
3902            uLogger.debug("Records about available funds for withdrawal successfully received")
3903
3904        return rawLimits
3905
3906    def OverviewLimits(self, show: bool = False) -> dict:
3907        """
3908        Method for parsing and show table with available funds for withdrawal for current `accountId`.
3909
3910        See also: `RequestLimits()`.
3911
3912        :param show: if `False` then only dictionary returns, if `True` then also print withdrawal limits to log.
3913        :return: dict with raw parsed data from server and some calculated statistics about it.
3914        """
3915        if self.accountId is None or not self.accountId:
3916            uLogger.error("Variable `accountId` must be defined for using this method!")
3917            raise Exception("Account ID required")
3918
3919        rawLimits = self.RequestLimits()  # raw response with current available funds for withdrawal
3920
3921        view = {
3922            "rawLimits": rawLimits,
3923            "limits": {  # parsed data for every currency:
3924                "money": {  # this is an array of portfolio currency positions
3925                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["money"]
3926                },
3927                "blocked": {  # this is an array of blocked currency
3928                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["blocked"]
3929                },
3930                "blockedGuarantee": {  # this is locked money under collateral for futures
3931                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["blockedGuarantee"]
3932                },
3933            },
3934        }
3935
3936        # --- Prepare text table with limits in human-readable format:
3937        if show:
3938            info = [
3939                "# Withdrawal limits\n\n",
3940                "* **Actual on date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
3941                "* **Account ID:** [{}]\n".format(self.accountId),
3942            ]
3943
3944            if view["limits"]["money"]:
3945                info.extend([
3946                    "\n| Currencies | Total         | Available for withdrawal | Blocked for trade | Futures guarantee |\n",
3947                    "|------------|---------------|--------------------------|-------------------|-------------------|\n",
3948                ])
3949
3950            else:
3951                info.append("\nNo withdrawal limits\n")
3952
3953            for curr in view["limits"]["money"].keys():
3954                blocked = view["limits"]["blocked"][curr] if curr in view["limits"]["blocked"].keys() else 0
3955                blockedGuarantee = view["limits"]["blockedGuarantee"][curr] if curr in view["limits"]["blockedGuarantee"].keys() else 0
3956                availableMoney = view["limits"]["money"][curr] - (blocked + blockedGuarantee)
3957
3958                infoStr = "| {:<10} | {:<13} | {:<24} | {:<17} | {:<17} |\n".format(
3959                    "[{}]".format(curr),
3960                    "{:.2f}".format(view["limits"]["money"][curr]),
3961                    "{:.2f}".format(availableMoney),
3962                    "{:.2f}".format(view["limits"]["blocked"][curr]) if curr in view["limits"]["blocked"].keys() else "—",
3963                    "{:.2f}".format(view["limits"]["blockedGuarantee"][curr]) if curr in view["limits"]["blockedGuarantee"].keys() else "—",
3964                )
3965
3966                if curr == "rub":
3967                    info.insert(5, infoStr)  # hack: insert "rub" at the first position in table and after headers
3968
3969                else:
3970                    info.append(infoStr)
3971
3972            infoText = "".join(info)
3973
3974            uLogger.info(infoText)
3975
3976            if self.withdrawalLimitsFile:
3977                with open(self.withdrawalLimitsFile, "w", encoding="UTF-8") as fH:
3978                    fH.write(infoText)
3979
3980                uLogger.info("Client's withdrawal limits was saved to file: [{}]".format(os.path.abspath(self.withdrawalLimitsFile)))
3981
3982                if self.useHTMLReports:
3983                    htmlFilePath = self.withdrawalLimitsFile.replace(".md", ".html") if self.withdrawalLimitsFile.endswith(".md") else self.withdrawalLimitsFile + ".html"
3984                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
3985                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Withdrawal limits", commonCSS=COMMON_CSS, markdown=infoText))
3986
3987                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
3988
3989        return view
3990
3991    def RequestAccounts(self) -> dict:
3992        """
3993        Method for requesting all brokerage accounts (`accountId`s) of current user detected by `token`.
3994
3995        See also:
3996        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetAccounts
3997        - What does account fields mean: https://tinkoff.github.io/investAPI/users/#account
3998        - `OverviewUserInfo()` method
3999
4000        :return: dict with raw data from server that contains accounts info. Example of dict:
4001                 `{"accounts": [{"id": "20000xxxxx", "type": "ACCOUNT_TYPE_TINKOFF", "name": "TKSBrokerAPI account",
4002                   "status": "ACCOUNT_STATUS_OPEN", "openedDate": "2018-05-23T00:00:00Z",
4003                   "closedDate": "1970-01-01T00:00:00Z", "accessLevel": "ACCOUNT_ACCESS_LEVEL_FULL_ACCESS"}, ...]}`.
4004                 If `closedDate="1970-01-01T00:00:00Z"` it means that account is active now.
4005        """
4006        uLogger.debug("Requesting all brokerage accounts of current user detected by its token. Wait, please...")
4007
4008        self.body = str({})
4009        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetAccounts"
4010        rawAccounts = self.SendAPIRequest(portfolioURL, reqType="POST")
4011
4012        if self.moreDebug:
4013            uLogger.debug("Records about available accounts successfully received")
4014
4015        return rawAccounts
4016
4017    def RequestUserInfo(self) -> dict:
4018        """
4019        Method for requesting common user's information.
4020
4021        See also:
4022        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetInfo
4023        - What does user info fields mean: https://tinkoff.github.io/investAPI/users/#getinforequest
4024        - What does `qualified_for_work_with` field mean: https://tinkoff.github.io/investAPI/faq_users/#qualified_for_work_with
4025        - `OverviewUserInfo()` method
4026
4027        :return: dict with raw data from server that contains user's information. Example of dict:
4028                 `{"premStatus": true, "qualStatus": false, "qualifiedForWorkWith": ["bond", "foreign_shares", "leverage",
4029                   "russian_shares", "structured_income_bonds"], "tariff": "premium"}`.
4030        """
4031        uLogger.debug("Requesting common user's information. Wait, please...")
4032
4033        self.body = str({})
4034        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetInfo"
4035        rawUserInfo = self.SendAPIRequest(portfolioURL, reqType="POST")
4036
4037        if self.moreDebug:
4038            uLogger.debug("Records about current user successfully received")
4039
4040        return rawUserInfo
4041
4042    def RequestMarginStatus(self, accountId: str = None) -> dict:
4043        """
4044        Method for requesting margin calculation for defined account ID.
4045
4046        See also:
4047        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetMarginAttributes
4048        - What does margin fields mean: https://tinkoff.github.io/investAPI/users/#getmarginattributesresponse
4049        - `OverviewUserInfo()` method
4050
4051        :param accountId: string with numeric account ID. If `None`, then used class field `accountId`.
4052        :return: dict with raw data from server that contains margin calculation. If margin is disabled then returns empty dict.
4053                 Example of responses:
4054                 status code 400: `{"code": 3, "message": "account margin status is disabled", "description": "30051" }`, returns: `{}`.
4055                 status code 200: `{"liquidPortfolio": {"currency": "rub", "units": "7175", "nano": 560000000},
4056                                    "startingMargin": {"currency": "rub", "units": "6311", "nano": 840000000},
4057                                    "minimalMargin": {"currency": "rub", "units": "3155", "nano": 920000000},
4058                                    "fundsSufficiencyLevel": {"units": "1", "nano": 280000000},
4059                                    "amountOfMissingFunds": {"currency": "rub", "units": "-863", "nano": -720000000}}`.
4060        """
4061        if accountId is None or not accountId:
4062            if self.accountId is None or not self.accountId:
4063                uLogger.error("Variable `accountId` must be defined for using this method!")
4064                raise Exception("Account ID required")
4065
4066            else:
4067                accountId = self.accountId  # use `self.accountId` (main ID) by default
4068
4069        uLogger.debug("Requesting margin calculation for accountId [{}]. Wait, please...".format(accountId))
4070
4071        self.body = str({"accountId": accountId})
4072        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetMarginAttributes"
4073        rawMargin = self.SendAPIRequest(portfolioURL, reqType="POST")
4074
4075        if rawMargin == {"code": 3, "message": "account margin status is disabled", "description": "30051"}:
4076            uLogger.debug("Server response: margin status is disabled for current accountId [{}]".format(accountId))
4077            rawMargin = {}
4078
4079        else:
4080            if self.moreDebug:
4081                uLogger.debug("Records with margin calculation for accountId [{}] successfully received".format(accountId))
4082
4083        return rawMargin
4084
4085    def RequestTariffLimits(self) -> dict:
4086        """
4087        Method for requesting limits of current tariff (connections, API methods etc.) of current user detected by `token`.
4088
4089        See also:
4090        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetUserTariff
4091        - What does fields in tariff mean: https://tinkoff.github.io/investAPI/users/#getusertariffrequest
4092        - Unary limit: https://tinkoff.github.io/investAPI/users/#unarylimit
4093        - Stream limit: https://tinkoff.github.io/investAPI/users/#streamlimit
4094        - `OverviewUserInfo()` method
4095
4096        :return: dict with raw data from server that contains limits of current tariff. Example of dict:
4097                 `{"unaryLimits": [{"limitPerMinute": 0, "methods": ["methods", "methods"]}, ...],
4098                   "streamLimits": [{"streams": ["streams", "streams"], "limit": 6}, ...]}`.
4099        """
4100        uLogger.debug("Requesting limits of current tariff. Wait, please...")
4101
4102        self.body = str({})
4103        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetUserTariff"
4104        rawTariffLimits = self.SendAPIRequest(portfolioURL, reqType="POST")
4105
4106        if self.moreDebug:
4107            uLogger.debug("Records with limits of current tariff successfully received")
4108
4109        return rawTariffLimits
4110
4111    def RequestBondCoupons(self, iJSON: dict) -> dict:
4112        """
4113        Requesting bond payment calendar from official placement date to maturity date. If these dates are unknown
4114        then requesting dates `"from": "1970-01-01T00:00:00.000Z"` and `"to": "2099-12-31T23:59:59.000Z"`.
4115        All dates are in UTC timezone.
4116
4117        REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_GetBondCoupons
4118        Documentation:
4119        - request: https://tinkoff.github.io/investAPI/instruments/#getbondcouponsrequest
4120        - response: https://tinkoff.github.io/investAPI/instruments/#coupon
4121
4122        See also: `ExtendBondsData()`.
4123
4124        :param iJSON: raw json data of a bond from broker server, example `iJSON = self.iList["Bonds"][self._ticker]`
4125                      If raw iJSON is not data of bond then server returns an error [400] with message:
4126                      `{"code": 3, "message": "instrument type is not bond", "description": "30048"}`.
4127        :return: dictionary with bond payment calendar. Response example
4128                 `{"events": [{"figi": "TCS00A101YV8", "couponDate": "2023-07-26T00:00:00Z", "couponNumber": "12",
4129                   "fixDate": "2023-07-25T00:00:00Z", "payOneBond": {"currency": "rub", "units": "7", "nano": 170000000},
4130                   "couponType": "COUPON_TYPE_CONSTANT", "couponStartDate": "2023-04-26T00:00:00Z",
4131                   "couponEndDate": "2023-07-26T00:00:00Z", "couponPeriod": 91}, {...}, ...]}`
4132        """
4133        if iJSON["figi"] is None or not iJSON["figi"]:
4134            uLogger.error("FIGI must be defined for using this method!")
4135            raise Exception("FIGI required")
4136
4137        startDate = iJSON["placementDate"] if "placementDate" in iJSON.keys() else "1970-01-01T00:00:00.000Z"
4138        endDate = iJSON["maturityDate"] if "maturityDate" in iJSON.keys() else "2099-12-31T23:59:59.000Z"
4139
4140        uLogger.debug("Requesting bond payment calendar, {}FIGI: [{}], from: [{}], to: [{}]. Wait, please...".format(
4141            "ticker: [{}], ".format(iJSON["ticker"]) if "ticker" in iJSON.keys() else "",
4142            self._figi,
4143            startDate,
4144            endDate,
4145        ))
4146
4147        self.body = str({"figi": iJSON["figi"], "from": startDate, "to": endDate})
4148        calendarURL = self.server + r"/tinkoff.public.invest.api.contract.v1.InstrumentsService/GetBondCoupons"
4149        calendar = self.SendAPIRequest(calendarURL, reqType="POST")
4150
4151        if calendar == {"code": 3, "message": "instrument type is not bond", "description": "30048"}:
4152            uLogger.warning("Instrument type is not bond!")
4153
4154        else:
4155            if self.moreDebug:
4156                uLogger.debug("Records about bond payment calendar successfully received")
4157
4158        return calendar
4159
4160    def ExtendBondsData(self, instruments: list[str], xlsx: bool = False) -> pd.DataFrame:
4161        """
4162        Requests jsons with raw bonds data for every ticker or FIGI in instruments list and transform it to the wider
4163        Pandas DataFrame with more information about bonds: main info, current prices, bond payment calendar,
4164        coupon yields, current yields and some statistics etc.
4165
4166        WARNING! This is too long operation if a lot of bonds requested from broker server.
4167
4168        See also: `ShowInstrumentInfo()`, `CreateBondsCalendar()`, `ShowBondsCalendar()`, `RequestBondCoupons()`.
4169
4170        :param instruments: list of strings with tickers or FIGIs.
4171        :param xlsx: if True then also exports Pandas DataFrame to xlsx-file `bondsXLSXFile`, default `ext-bonds.xlsx`,
4172                     for further used by data scientists or stock analytics.
4173        :return: wider Pandas DataFrame with more full and calculated data about bonds, than raw response from broker.
4174                 In XLSX-file and Pandas DataFrame fields mean:
4175                 - main info about bond: https://tinkoff.github.io/investAPI/instruments/#bond
4176                 - info about coupon: https://tinkoff.github.io/investAPI/instruments/#coupon
4177        """
4178        if instruments is None or not instruments:
4179            uLogger.error("List of tickers or FIGIs must be defined for using this method!")
4180            raise Exception("Ticker or FIGI required")
4181
4182        if isinstance(instruments, str):
4183            instruments = [instruments]
4184
4185        uniqueInstruments = self.GetUniqueFIGIs(instruments)
4186
4187        uLogger.debug("Requesting raw bonds calendar from server, transforming and extending it. Wait, please...")
4188
4189        iCount = len(uniqueInstruments)
4190        tooLong = iCount >= 20
4191        if tooLong:
4192            uLogger.warning("You requested a lot of bonds! Operation will takes more time. Wait, please...")
4193
4194        bonds = None
4195        for i, self._figi in enumerate(uniqueInstruments):
4196            instrument = self.SearchByFIGI(requestPrice=False)  # raw data about instrument from server
4197
4198            if "type" in instrument.keys() and instrument["type"] == "Bonds":
4199                # raw bond data from server where fields mean: https://tinkoff.github.io/investAPI/instruments/#bond
4200                rawBond = self.SearchByFIGI(requestPrice=True)
4201
4202                # Widen raw data with UTC current time (iData["actualDateTime"]):
4203                actualDate = datetime.now(tzutc())
4204                iData = {"actualDateTime": actualDate.strftime(TKS_DATE_TIME_FORMAT)} | rawBond
4205
4206                # Widen raw data with bond payment calendar (iData["rawCalendar"]):
4207                iData = iData | {"rawCalendar": self.RequestBondCoupons(iJSON=iData)}
4208
4209                # Replace some values with human-readable:
4210                iData["nominalCurrency"] = iData["nominal"]["currency"]
4211                iData["nominal"] = NanoToFloat(iData["nominal"]["units"], iData["nominal"]["nano"])
4212                iData["placementPrice"] = NanoToFloat(iData["placementPrice"]["units"], iData["placementPrice"]["nano"])
4213                iData["aciCurrency"] = iData["aciValue"]["currency"]
4214                iData["aciValue"] = NanoToFloat(iData["aciValue"]["units"], iData["aciValue"]["nano"])
4215                iData["issueSize"] = int(iData["issueSize"])
4216                iData["issueSizePlan"] = int(iData["issueSizePlan"])
4217                iData["tradingStatus"] = TKS_TRADING_STATUSES[iData["tradingStatus"]]
4218                iData["step"] = iData["step"] if "step" in iData.keys() else 0
4219                iData["realExchange"] = TKS_REAL_EXCHANGES[iData["realExchange"]]
4220                iData["klong"] = NanoToFloat(iData["klong"]["units"], iData["klong"]["nano"]) if "klong" in iData.keys() else 0
4221                iData["kshort"] = NanoToFloat(iData["kshort"]["units"], iData["kshort"]["nano"]) if "kshort" in iData.keys() else 0
4222                iData["dlong"] = NanoToFloat(iData["dlong"]["units"], iData["dlong"]["nano"]) if "dlong" in iData.keys() else 0
4223                iData["dshort"] = NanoToFloat(iData["dshort"]["units"], iData["dshort"]["nano"]) if "dshort" in iData.keys() else 0
4224                iData["dlongMin"] = NanoToFloat(iData["dlongMin"]["units"], iData["dlongMin"]["nano"]) if "dlongMin" in iData.keys() else 0
4225                iData["dshortMin"] = NanoToFloat(iData["dshortMin"]["units"], iData["dshortMin"]["nano"]) if "dshortMin" in iData.keys() else 0
4226
4227                # Widen raw data with price fields from `currentPrice` values (all prices are actual at `actualDateTime` date):
4228                iData["limitUpPercent"] = iData["currentPrice"]["limitUp"]  # max price on current day in percents of nominal
4229                iData["limitDownPercent"] = iData["currentPrice"]["limitDown"]  # min price on current day in percents of nominal
4230                iData["lastPricePercent"] = iData["currentPrice"]["lastPrice"]  # last price on market in percents of nominal
4231                iData["closePricePercent"] = iData["currentPrice"]["closePrice"]  # previous day close in percents of nominal
4232                iData["changes"] = iData["currentPrice"]["changes"]  # this is percent of changes between `currentPrice` and `lastPrice`
4233                iData["limitUp"] = iData["limitUpPercent"] * iData["nominal"] / 100  # max price on current day is `limitUpPercent` * `nominal`
4234                iData["limitDown"] = iData["limitDownPercent"] * iData["nominal"] / 100  # min price on current day is `limitDownPercent` * `nominal`
4235                iData["lastPrice"] = iData["lastPricePercent"] * iData["nominal"] / 100  # last price on market is `lastPricePercent` * `nominal`
4236                iData["closePrice"] = iData["closePricePercent"] * iData["nominal"] / 100  # previous day close is `closePricePercent` * `nominal`
4237                iData["changesDelta"] = iData["lastPrice"] - iData["closePrice"]  # this is delta between last deal price and last close
4238
4239                # Widen raw data with calendar data from `rawCalendar` values:
4240                calendarData = []
4241                if "events" in iData["rawCalendar"].keys():
4242                    for item in iData["rawCalendar"]["events"]:
4243                        calendarData.append({
4244                            "couponDate": item["couponDate"],
4245                            "couponNumber": int(item["couponNumber"]),
4246                            "fixDate": item["fixDate"] if "fixDate" in item.keys() else "",
4247                            "payCurrency": item["payOneBond"]["currency"],
4248                            "payOneBond": NanoToFloat(item["payOneBond"]["units"], item["payOneBond"]["nano"]),
4249                            "couponType": TKS_COUPON_TYPES[item["couponType"]],
4250                            "couponStartDate": item["couponStartDate"],
4251                            "couponEndDate": item["couponEndDate"],
4252                            "couponPeriod": item["couponPeriod"],
4253                        })
4254
4255                    # if maturity date is unknown then uses the latest date in bond payment calendar for it:
4256                    if "maturityDate" not in iData.keys():
4257                        iData["maturityDate"] = datetime.strptime(calendarData[0]["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_DATE_TIME_FORMAT) if calendarData else ""
4258
4259                # Widen raw data with Coupon Rate.
4260                # This is sum of all coupon payments divided on nominal price and expire days sum and then multiple on 365 days and 100%:
4261                iData["sumCoupons"] = sum([coupon["payOneBond"] for coupon in calendarData])
4262                iData["periodDays"] = sum([coupon["couponPeriod"] for coupon in calendarData])
4263                iData["couponsYield"] = 100 * 365 * (iData["sumCoupons"] / iData["nominal"]) / iData["periodDays"] if iData["nominal"] != 0 and iData["periodDays"] != 0 else 0.
4264
4265                # Widen raw data with Yield to Maturity (YTM) on current date.
4266                # This is sum of all stayed coupons to maturity minus ACI and divided on current bond price and then multiple on stayed days and 100%:
4267                maturityDate = datetime.strptime(iData["maturityDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()) if iData["maturityDate"] else None
4268                iData["daysToMaturity"] = (maturityDate - actualDate).days if iData["maturityDate"] else None
4269                iData["sumLastCoupons"] = sum([coupon["payOneBond"] for coupon in calendarData if datetime.strptime(coupon["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()) > actualDate])
4270                iData["lastPayments"] = iData["sumLastCoupons"] - iData["aciValue"]  # sum of all last coupons minus current ACI value
4271                iData["currentYield"] = 100 * 365 * (iData["lastPayments"] / iData["lastPrice"]) / iData["daysToMaturity"] if iData["lastPrice"] != 0 and iData["daysToMaturity"] != 0 else 0.
4272
4273                iData["calendar"] = calendarData  # adds calendar at the end
4274
4275                # Remove not used data:
4276                iData.pop("uid")
4277                iData.pop("positionUid")
4278                iData.pop("currentPrice")
4279                iData.pop("rawCalendar")
4280
4281                colNames = list(iData.keys())
4282                if bonds is None:
4283                    bonds = pd.DataFrame(data=pd.DataFrame.from_records(data=[iData], columns=colNames))
4284
4285                else:
4286                    bonds = pd.concat([bonds, pd.DataFrame.from_records(data=[iData], columns=colNames)], axis=0, ignore_index=True)
4287
4288            else:
4289                uLogger.warning("Instrument is not a bond!")
4290
4291            processed = round(100 * (i + 1) / iCount, 1)
4292            if tooLong and processed % 5 == 0:
4293                uLogger.info("{}% processed [{} / {}]...".format(round(processed), i + 1, iCount))
4294
4295            else:
4296                uLogger.debug("{}% bonds processed [{} / {}]...".format(processed, i + 1, iCount))
4297
4298        bonds.index = bonds["ticker"].tolist()  # replace indexes with ticker names
4299
4300        # Saving bonds from Pandas DataFrame to XLSX sheet:
4301        if xlsx and self.bondsXLSXFile:
4302            with pd.ExcelWriter(
4303                    path=self.bondsXLSXFile,
4304                    date_format=TKS_DATE_FORMAT,
4305                    datetime_format=TKS_DATE_TIME_FORMAT,
4306                    mode="w",
4307            ) as writer:
4308                bonds.to_excel(
4309                    writer,
4310                    sheet_name="Extended bonds data",
4311                    index=True,
4312                    encoding="UTF-8",
4313                    freeze_panes=(1, 1),
4314                )  # saving as XLSX-file with freeze first row and column as headers
4315
4316            uLogger.info("XLSX-file with extended bonds data for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(self.bondsXLSXFile)))
4317
4318        return bonds
4319
4320    def CreateBondsCalendar(self, extBonds: pd.DataFrame, xlsx: bool = False) -> pd.DataFrame:
4321        """
4322        Creates bond payments calendar as Pandas DataFrame, and also save it to the XLSX-file, `calendar.xlsx` by default.
4323
4324        WARNING! This is too long operation if a lot of bonds requested from broker server.
4325
4326        See also: `ShowBondsCalendar()`, `ExtendBondsData()`.
4327
4328        :param extBonds: Pandas DataFrame object returns by `ExtendBondsData()` method and contains
4329                        extended information about bonds: main info, current prices, bond payment calendar,
4330                        coupon yields, current yields and some statistics etc.
4331                        If this parameter is `None` then used `figi` or `ticker` as bond name and then calculate `ExtendBondsData()`.
4332        :param xlsx: if True then also exports Pandas DataFrame to file `calendarFile` + `".xlsx"`, `calendar.xlsx` by default,
4333                     for further used by data scientists or stock analytics.
4334        :return: Pandas DataFrame with only bond payments calendar data. Fields mean: https://tinkoff.github.io/investAPI/instruments/#coupon
4335        """
4336        if extBonds is None or not isinstance(extBonds, pd.DataFrame) or extBonds.empty:
4337            extBonds = self.ExtendBondsData(instruments=[self._figi, self._ticker], xlsx=False)
4338
4339        uLogger.debug("Generating bond payments calendar data. Wait, please...")
4340
4341        colNames = ["Paid", "Payment date", "FIGI", "Ticker", "Name", "No.", "Value", "Currency", "Coupon type", "Period", "End registry date", "Coupon start date", "Coupon end date"]
4342        colID = ["paid", "couponDate", "figi", "ticker", "name", "couponNumber", "payOneBond", "payCurrency", "couponType", "couponPeriod", "fixDate", "couponStartDate", "couponEndDate"]
4343        calendar = None
4344        for bond in extBonds.iterrows():
4345            for item in bond[1]["calendar"]:
4346                cData = {
4347                    "paid": datetime.now(tzutc()) > datetime.strptime(item["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()),
4348                    "couponDate": item["couponDate"],
4349                    "figi": bond[1]["figi"],
4350                    "ticker": bond[1]["ticker"],
4351                    "name": bond[1]["name"],
4352                    "couponNumber": item["couponNumber"],
4353                    "payOneBond": item["payOneBond"],
4354                    "payCurrency": item["payCurrency"],
4355                    "couponType": item["couponType"],
4356                    "couponPeriod": item["couponPeriod"],
4357                    "fixDate": item["fixDate"],
4358                    "couponStartDate": item["couponStartDate"],
4359                    "couponEndDate": item["couponEndDate"],
4360                }
4361
4362                if calendar is None:
4363                    calendar = pd.DataFrame(data=pd.DataFrame.from_records(data=[cData], columns=colID))
4364
4365                else:
4366                    calendar = pd.concat([calendar, pd.DataFrame.from_records(data=[cData], columns=colID)], axis=0, ignore_index=True)
4367
4368        if calendar is not None:
4369            calendar = calendar.sort_values(by=["couponDate"], axis=0, ascending=True)  # sort all payments for all bonds by payment date
4370
4371            # Saving calendar from Pandas DataFrame to XLSX sheet:
4372            if xlsx:
4373                xlsxCalendarFile = self.calendarFile.replace(".md", ".xlsx") if self.calendarFile.endswith(".md") else self.calendarFile + ".xlsx"
4374
4375                with pd.ExcelWriter(
4376                        path=xlsxCalendarFile,
4377                        date_format=TKS_DATE_FORMAT,
4378                        datetime_format=TKS_DATE_TIME_FORMAT,
4379                        mode="w",
4380                ) as writer:
4381                    humanReadable = calendar.copy(deep=True)
4382                    humanReadable["couponDate"] = humanReadable["couponDate"].apply(lambda x: x.split("T")[0])
4383                    humanReadable["fixDate"] = humanReadable["fixDate"].apply(lambda x: x.split("T")[0])
4384                    humanReadable["couponStartDate"] = humanReadable["couponStartDate"].apply(lambda x: x.split("T")[0])
4385                    humanReadable["couponEndDate"] = humanReadable["couponEndDate"].apply(lambda x: x.split("T")[0])
4386                    humanReadable.columns = colNames  # human-readable column names
4387
4388                    humanReadable.to_excel(
4389                        writer,
4390                        sheet_name="Bond payments calendar",
4391                        index=False,
4392                        encoding="UTF-8",
4393                        freeze_panes=(1, 2),
4394                    )  # saving as XLSX-file with freeze first row and column as headers
4395
4396                    del humanReadable  # release df in memory
4397
4398                uLogger.info("XLSX-file with bond payments calendar for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(xlsxCalendarFile)))
4399
4400        return calendar
4401
4402    def ShowBondsCalendar(self, extBonds: pd.DataFrame, show: bool = True) -> str:
4403        """
4404        Show bond payments calendar as a table. One row in input `bonds` dataframe contains one bond.
4405        Also, creates Markdown file with calendar data, `calendar.md` by default.
4406
4407        See also: `ShowInstrumentInfo()`, `RequestBondCoupons()`, `CreateBondsCalendar()` and `ExtendBondsData()`.
4408
4409        :param extBonds: Pandas DataFrame object returns by `ExtendBondsData()` method and contains
4410                        extended information about bonds: main info, current prices, bond payment calendar,
4411                        coupon yields, current yields and some statistics etc.
4412                        If this parameter is `None` then used `figi` or `ticker` as bond name and then calculate `ExtendBondsData()`.
4413        :param show: if `True` then also printing bonds payment calendar to the console,
4414                     otherwise save to file `calendarFile` only. `False` by default.
4415        :return: multilines text in Markdown format with bonds payment calendar as a table.
4416        """
4417        if extBonds is None or not isinstance(extBonds, pd.DataFrame) or extBonds.empty:
4418            extBonds = self.ExtendBondsData(instruments=[self._figi, self._ticker], xlsx=False)
4419
4420        infoText = "# Bond payments calendar\n\n"
4421
4422        calendar = self.CreateBondsCalendar(extBonds, xlsx=True)  # generate Pandas DataFrame with full calendar data
4423
4424        if not (calendar is None or calendar.empty):
4425            splitLine = "|       |                 |              |              |     |               |           |        |                   |\n"
4426
4427            info = [
4428                "* **Actual on date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
4429                "| Paid  | Payment date    | FIGI         | Ticker       | No. | Value         | Type      | Period | End registry date |\n",
4430                "|-------|-----------------|--------------|--------------|-----|---------------|-----------|--------|-------------------|\n",
4431            ]
4432
4433            newMonth = False
4434            notOneBond = calendar["figi"].nunique() > 1
4435            for i, bond in enumerate(calendar.iterrows()):
4436                if newMonth and notOneBond:
4437                    info.append(splitLine)
4438
4439                info.append(
4440                    "| {:<5} | {:<15} | {:<12} | {:<12} | {:<3} | {:<13} | {:<9} | {:<6} | {:<17} |\n".format(
4441                        "  √" if bond[1]["paid"] else "  —",
4442                        bond[1]["couponDate"].split("T")[0],
4443                        bond[1]["figi"],
4444                        bond[1]["ticker"],
4445                        bond[1]["couponNumber"],
4446                        "{} {}".format(
4447                            "{}".format(round(bond[1]["payOneBond"], 6)).rstrip("0").rstrip("."),
4448                            bond[1]["payCurrency"],
4449                        ),
4450                        bond[1]["couponType"],
4451                        bond[1]["couponPeriod"],
4452                        bond[1]["fixDate"].split("T")[0],
4453                    )
4454                )
4455
4456                if i < len(calendar.values) - 1:
4457                    curDate = datetime.strptime(bond[1]["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc())
4458                    nextDate = datetime.strptime(calendar["couponDate"].values[i + 1], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc())
4459                    newMonth = False if curDate.month == nextDate.month else True
4460
4461                else:
4462                    newMonth = False
4463
4464            infoText += "".join(info)
4465
4466            if show:
4467                uLogger.info("{}".format(infoText))
4468
4469            if self.calendarFile is not None:
4470                with open(self.calendarFile, "w", encoding="UTF-8") as fH:
4471                    fH.write(infoText)
4472
4473                uLogger.info("Bond payments calendar was saved to file: [{}]".format(os.path.abspath(self.calendarFile)))
4474
4475                if self.useHTMLReports:
4476                    htmlFilePath = self.calendarFile.replace(".md", ".html") if self.calendarFile.endswith(".md") else self.calendarFile + ".html"
4477                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
4478                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Bond payments calendar", commonCSS=COMMON_CSS, markdown=infoText))
4479
4480                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
4481
4482        else:
4483            infoText += "No data\n"
4484
4485        return infoText
4486
4487    def OverviewAccounts(self, show: bool = False) -> dict:
4488        """
4489        Method for parsing and show simple table with all available user accounts.
4490
4491        See also: `RequestAccounts()` and `OverviewUserInfo()` methods.
4492
4493        :param show: if `False` then only dictionary with accounts data returns, if `True` then also print it to log.
4494        :return: dict with parsed accounts data received from `RequestAccounts()` method. Example of dict:
4495                 `view = {"rawAccounts": {rawAccounts from RequestAccounts() method...},
4496                          "stat": {"accountId string": {"type": "Tinkoff brokerage account", "name": "Test - 1",
4497                                                        "status": "Opened and active account", "opened": "2018-05-23 00:00:00",
4498                                                        "closed": "—", "access": "Full access" }, ...}}`
4499        """
4500        rawAccounts = self.RequestAccounts()  # Raw responses with accounts
4501
4502        # This is an array of dict with user accounts, its `accountId`s and some parsed data:
4503        accounts = {
4504            item["id"]: {
4505                "type": TKS_ACCOUNT_TYPES[item["type"]],
4506                "name": item["name"],
4507                "status": TKS_ACCOUNT_STATUSES[item["status"]],
4508                "opened": datetime.strptime(item["openedDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
4509                "closed": datetime.strptime(item["closedDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT) if item["closedDate"] != "1970-01-01T00:00:00Z" else "—",
4510                "access": TKS_ACCESS_LEVELS[item["accessLevel"]],
4511            } for item in rawAccounts["accounts"]
4512        }
4513
4514        # Raw and parsed data with some fields replaced in "stat" section:
4515        view = {
4516            "rawAccounts": rawAccounts,
4517            "stat": accounts,
4518        }
4519
4520        # --- Prepare simple text table with only accounts data in human-readable format:
4521        if show:
4522            info = [
4523                "# User accounts\n\n",
4524                "* **Actual date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
4525                "| Account ID   | Type                      | Status                    | Name                           |\n",
4526                "|--------------|---------------------------|---------------------------|--------------------------------|\n",
4527            ]
4528
4529            for account in view["stat"].keys():
4530                info.extend([
4531                    "| {:<12} | {:<25} | {:<25} | {:<30} |\n".format(
4532                        account,
4533                        view["stat"][account]["type"],
4534                        view["stat"][account]["status"],
4535                        view["stat"][account]["name"],
4536                    )
4537                ])
4538
4539            infoText = "".join(info)
4540
4541            uLogger.info(infoText)
4542
4543            if self.userAccountsFile:
4544                with open(self.userAccountsFile, "w", encoding="UTF-8") as fH:
4545                    fH.write(infoText)
4546
4547                uLogger.info("User accounts were saved to file: [{}]".format(os.path.abspath(self.userAccountsFile)))
4548
4549                if self.useHTMLReports:
4550                    htmlFilePath = self.userAccountsFile.replace(".md", ".html") if self.userAccountsFile.endswith(".md") else self.userAccountsFile + ".html"
4551                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
4552                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="User accounts", commonCSS=COMMON_CSS, markdown=infoText))
4553
4554                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
4555
4556        return view
4557
4558    def OverviewUserInfo(self, show: bool = False) -> dict:
4559        """
4560        Method for parsing and show all available user's data (`accountId`s, common user information, margin status and tariff connections limit).
4561
4562        See also: `OverviewAccounts()`, `RequestAccounts()`, `RequestUserInfo()`, `RequestMarginStatus()` and `RequestTariffLimits()` methods.
4563
4564        :param show: if `False` then only dictionary returns, if `True` then also print user's data to log.
4565        :return: dict with raw parsed data from server and some calculated statistics about it.
4566        """
4567        overview = self.Overview(show=False)  # Request current user portfolio for the ability to calculate missing funds
4568        tmpTicker = self._ticker
4569        self._ticker = "RUB000UTSTOM"  # This instrument show in rub how much money cost current margin
4570        missing = self.GetInstrumentFromPortfolio(portfolio=overview)
4571        self._ticker = tmpTicker
4572
4573        rawUserInfo = self.RequestUserInfo()  # Raw response with common user info
4574        overviewAccount = self.OverviewAccounts(show=False)  # Raw and parsed accounts data
4575        rawAccounts = overviewAccount["rawAccounts"]  # Raw response with user accounts data
4576        accounts = overviewAccount["stat"]  # Dict with only statistics about user accounts
4577        rawMargins = {account: self.RequestMarginStatus(accountId=account) for account in accounts.keys()}  # Raw response with margin calculation for every account ID
4578        rawTariffLimits = self.RequestTariffLimits()  # Raw response with limits of current tariff
4579
4580        # This is dict with parsed common user data:
4581        userInfo = {
4582            "premium": "Yes" if rawUserInfo["premStatus"] else "No",
4583            "qualified": "Yes" if rawUserInfo["qualStatus"] else "No",
4584            "allowed": [TKS_QUALIFIED_TYPES[item] for item in rawUserInfo["qualifiedForWorkWith"]],
4585            "tariff": rawUserInfo["tariff"],
4586        }
4587
4588        # This is an array of dict with parsed margin statuses for every account IDs:
4589        margins = {}
4590        for accountId in accounts.keys():
4591            if rawMargins[accountId]:
4592                margins[accountId] = {
4593                    "currency": rawMargins[accountId]["liquidPortfolio"]["currency"],
4594                    "liquid": NanoToFloat(rawMargins[accountId]["liquidPortfolio"]["units"], rawMargins[accountId]["liquidPortfolio"]["nano"]),
4595                    "start": NanoToFloat(rawMargins[accountId]["startingMargin"]["units"], rawMargins[accountId]["startingMargin"]["nano"]),
4596                    "min": NanoToFloat(rawMargins[accountId]["minimalMargin"]["units"], rawMargins[accountId]["minimalMargin"]["nano"]),
4597                    "diff": NanoToFloat(rawMargins[accountId]["amountOfMissingFunds"]["units"], rawMargins[accountId]["amountOfMissingFunds"]["nano"]),
4598                    "level": NanoToFloat(rawMargins[accountId]["fundsSufficiencyLevel"]["units"], rawMargins[accountId]["fundsSufficiencyLevel"]["nano"]),
4599                    "missing": missing["volume"],
4600                }
4601
4602            else:
4603                margins[accountId] = {}  # Server response: margin status is disabled for current accountId
4604
4605        unary = {}  # unary-connection limits
4606        for item in rawTariffLimits["unaryLimits"]:
4607            if item["limitPerMinute"] in unary.keys():
4608                unary[item["limitPerMinute"]].extend(item["methods"])
4609
4610            else:
4611                unary[item["limitPerMinute"]] = item["methods"]
4612
4613        stream = {}  # stream-connection limits
4614        for item in rawTariffLimits["streamLimits"]:
4615            if item["limit"] in stream.keys():
4616                stream[item["limit"]].extend(item["streams"])
4617
4618            else:
4619                stream[item["limit"]] = item["streams"]
4620
4621        # This is dict with parsed limits of current tariff (connections, API methods etc.):
4622        limits = {
4623            "unary": unary,
4624            "stream": stream,
4625        }
4626
4627        # Raw and parsed data as an output result:
4628        view = {
4629            "rawUserInfo": rawUserInfo,
4630            "rawAccounts": rawAccounts,
4631            "rawMargins": rawMargins,
4632            "rawTariffLimits": rawTariffLimits,
4633            "stat": {
4634                "overview": overview,
4635                "userInfo": userInfo,
4636                "accounts": accounts,
4637                "margins": margins,
4638                "limits": limits,
4639            },
4640        }
4641
4642        # --- Prepare text table with user information in human-readable format:
4643        if show:
4644            info = [
4645                "# Full user information\n\n",
4646                "* **Actual date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
4647                "## Common information\n\n",
4648                "* **Qualified user:** {}\n".format(view["stat"]["userInfo"]["qualified"]),
4649                "* **Tariff name:** {}\n".format(view["stat"]["userInfo"]["tariff"]),
4650                "* **Premium user:** {}\n".format(view["stat"]["userInfo"]["premium"]),
4651                "* **Allowed to work with instruments:**\n{}\n".format("".join(["  - {}\n".format(item) for item in view["stat"]["userInfo"]["allowed"]])),
4652                "\n## User accounts\n\n",
4653            ]
4654
4655            for account in view["stat"]["accounts"].keys():
4656                info.extend([
4657                    "### ID: [{}]\n\n".format(account),
4658                    "| Parameters           | Values                                                       |\n",
4659                    "|----------------------|--------------------------------------------------------------|\n",
4660                    "| Account type:        | {:<60} |\n".format(view["stat"]["accounts"][account]["type"]),
4661                    "| Account name:        | {:<60} |\n".format(view["stat"]["accounts"][account]["name"]),
4662                    "| Account status:      | {:<60} |\n".format(view["stat"]["accounts"][account]["status"]),
4663                    "| Access level:        | {:<60} |\n".format(view["stat"]["accounts"][account]["access"]),
4664                    "| Date opened:         | {:<60} |\n".format(view["stat"]["accounts"][account]["opened"]),
4665                    "| Date closed:         | {:<60} |\n".format(view["stat"]["accounts"][account]["closed"]),
4666                ])
4667
4668                if margins[account]:
4669                    info.extend([
4670                        "| Margin status:       | Enabled                                                      |\n",
4671                        "| - Liquid portfolio:  | {:<60} |\n".format("{} {}".format(margins[account]["liquid"], margins[account]["currency"])),
4672                        "| - Margin starting:   | {:<60} |\n".format("{} {}".format(margins[account]["start"], margins[account]["currency"])),
4673                        "| - Margin minimum:    | {:<60} |\n".format("{} {}".format(margins[account]["min"], margins[account]["currency"])),
4674                        "| - Margin difference: | {:<60} |\n".format("{} {}".format(margins[account]["diff"], margins[account]["currency"])),
4675                        "| - Sufficiency level: | {:<60} |\n".format("{:.2f} ({:.2f}%)".format(margins[account]["level"], margins[account]["level"] * 100)),
4676                        "| - Not covered funds: | {:<60} |\n\n".format("{:.2f} {}".format(margins[account]["missing"], margins[account]["currency"])),
4677                    ])
4678
4679                else:
4680                    info.append("| Margin status:       | Disabled                                                     |\n\n")
4681
4682            info.extend([
4683                "\n## Current user tariff limits\n",
4684                "\n### See also\n",
4685                "* Tinkoff limit policy: https://tinkoff.github.io/investAPI/limits/\n",
4686                "* Tinkoff Invest API: https://tinkoff.github.io/investAPI/\n",
4687                "  - More about REST API requests: https://tinkoff.github.io/investAPI/swagger-ui/\n",
4688                "  - More about gRPC requests for stream connections: https://tinkoff.github.io/investAPI/grpc/\n",
4689                "\n### Unary limits\n",
4690            ])
4691
4692            if unary:
4693                for key, values in sorted(unary.items()):
4694                    info.append("\n* Max requests per minute: {}\n".format(key))
4695
4696                    for value in values:
4697                        info.append("  - {}\n".format(value))
4698
4699            else:
4700                info.append("\nNot available\n")
4701
4702            info.append("\n### Stream limits\n")
4703
4704            if stream:
4705                for key, values in sorted(stream.items()):
4706                    info.append("\n* Max stream connections: {}\n".format(key))
4707
4708                    for value in values:
4709                        info.append("  - {}\n".format(value))
4710
4711            else:
4712                info.append("\nNot available\n")
4713
4714            infoText = "".join(info)
4715
4716            uLogger.info(infoText)
4717
4718            if self.userInfoFile:
4719                with open(self.userInfoFile, "w", encoding="UTF-8") as fH:
4720                    fH.write(infoText)
4721
4722                uLogger.info("User data was saved to file: [{}]".format(os.path.abspath(self.userInfoFile)))
4723
4724                if self.useHTMLReports:
4725                    htmlFilePath = self.userInfoFile.replace(".md", ".html") if self.userInfoFile.endswith(".md") else self.userInfoFile + ".html"
4726                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
4727                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="User info", commonCSS=COMMON_CSS, markdown=infoText))
4728
4729                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
4730
4731        return view
4732
4733
4734class Args:
4735    """
4736    If `Main()` function is imported as module, then this class used to convert arguments from **kwargs as object.
4737    """
4738    def __init__(self, **kwargs):
4739        self.__dict__.update(kwargs)
4740
4741    def __getattr__(self, item):
4742        return None
4743
4744
4745def ParseArgs():
4746    """This function get and parse command line keys."""
4747    parser = ArgumentParser()  # command-line string parser
4748
4749    parser.description = "TKSBrokerAPI is a trading platform for automation on Python to simplify the implementation of trading scenarios and work with Tinkoff Invest API server via the REST protocol. See examples: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md"
4750    parser.usage = "\n/as module/ python TKSBrokerAPI.py [some options] [one command]\n/as CLI tool/ tksbrokerapi [some options] [one command]"
4751
4752    # --- options:
4753
4754    parser.add_argument("--no-cache", action="store_true", default=False, help="Option: not use local cache `dump.json`, but update raw instruments data when starting the platform. `False` by default.")
4755    parser.add_argument("--token", type=str, help="Option: Tinkoff service's api key. If not set then used environment variable `TKS_API_TOKEN`. See how to use: https://tinkoff.github.io/investAPI/token/")
4756    parser.add_argument("--account-id", type=str, default=None, help="Option: string with an user numeric account ID in Tinkoff Broker. It can be found in any broker's reports (see the contract number). Also, this variable can be set from environment variable `TKS_ACCOUNT_ID`.")
4757
4758    parser.add_argument("--ticker", "-t", type=str, help="Option: instrument's ticker, e.g. `IBM`, `YNDX`, `GOOGL` etc. Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR`.")
4759    parser.add_argument("--figi", "-f", type=str, help="Option: instrument's FIGI, e.g. `BBG006L8G4H1` (for `YNDX`).")
4760
4761    parser.add_argument("--depth", type=int, default=1, help="Option: Depth of Market (DOM) can be >=1, 1 by default.")
4762    parser.add_argument("--no-cancelled", "--no-canceled", action="store_true", default=False, help="Option: remove information about cancelled operations from the deals report by the `--deals` key. `False` by default.")
4763
4764    parser.add_argument("--output", type=str, default=None, help="Option: replace default paths to output files for some commands. If `None` then used default files.")
4765    parser.add_argument("--html", "--HTML", action="store_true", default=False, help="Option: if key present then TKSBrokerAPI generate also HTML reports from Markdown. False by default.")
4766
4767    parser.add_argument("--interval", type=str, default="hour", help="Option: available values are `1min`, `5min`, `15min`, `hour` and `day`. Used only with `--history` key. This is time period of one candle. Default: `hour` for every history candles.")
4768    parser.add_argument("--only-missing", action="store_true", default=False, help="Option: if history file define by `--output` key then add only last missing candles, do not request all history length. `False` by default.")
4769    parser.add_argument("--csv-sep", type=str, default=",", help="Option: separator if csv-file is used, `,` by default.")
4770
4771    parser.add_argument("--debug-level", "--log-level", "--verbosity", "-v", type=int, default=20, help="Option: showing STDOUT messages of minimal debug level, e.g. 10 = DEBUG, 20 = INFO, 30 = WARNING, 40 = ERROR, 50 = CRITICAL. INFO (20) by default.")
4772    parser.add_argument("--more", "--more-debug", action="store_true", default=False, help="Option: `--debug-level` key only switch log level verbosity, but in addition `--more` key enable all debug information, such as net request and response headers in all methods.")
4773
4774    # --- commands:
4775
4776    parser.add_argument("--version", "--ver", action="store_true", help="Action: shows current semantic version, looks like `major.minor.buildnumber`. If TKSBrokerAPI not installed via pip, then used local build number `.dev0`.")
4777
4778    parser.add_argument("--list", "-l", action="store_true", help="Action: get and print all available instruments and some information from broker server. Also, you can define `--output` key to save list of instruments to file, default: `instruments.md`.")
4779    parser.add_argument("--list-xlsx", "-x", action="store_true", help="Action: get all available instruments from server for current account and save raw data into xlsx-file for further used by data scientists or stock analytics, default: `dump.xlsx`.")
4780    parser.add_argument("--bonds-xlsx", "-b", type=str, nargs="*", help="Action: get all available bonds if only key present or list of bonds with FIGIs or tickers and transform it to the wider Pandas DataFrame with more information about bonds: main info, current prices, bonds payment calendar, coupon yields, current yields and some statistics etc. And then export data to XLSX-file, default: `ext-bonds.xlsx` or you can change it with `--output` key. WARNING! This is too long operation if a lot of bonds requested from broker server.")
4781    parser.add_argument("--search", "-s", type=str, nargs=1, help="Action: search for an instruments by part of the name, ticker or FIGI. Also, you can define `--output` key to save results to file, default: `search-results.md`.")
4782    parser.add_argument("--info", "-i", action="store_true", help="Action: get information from broker server about instrument by it's ticker or FIGI. `--ticker` key or `--figi` key must be defined!")
4783    parser.add_argument("--calendar", "-c", type=str, nargs="*", help="Action: show bonds payment calendar as a table. Calendar build for one or more tickers or FIGIs, or for all bonds if only key present. If the `--output` key present then calendar saves to file, default: `calendar.md`. Also, created XLSX-file with bond payments calendar for further used by data scientists or stock analytics, `calendar.xlsx` by default. WARNING! This is too long operation if a lot of bonds requested from broker server.")
4784    parser.add_argument("--price", action="store_true", help="Action: show actual price list for current instrument. Also, you can use `--depth` key. `--ticker` key or `--figi` key must be defined!")
4785    parser.add_argument("--prices", "-p", type=str, nargs="+", help="Action: get and print current prices for list of given instruments (by it's tickers or by FIGIs). WARNING! This is too long operation if you request a lot of instruments! Also, you can define `--output` key to save list of prices to file, default: `prices.md`.")
4786
4787    parser.add_argument("--overview", "-o", action="store_true", help="Action: shows all open positions, orders and some statistics. Also, you can define `--output` key to save this information to file, default: `overview.md`.")
4788    parser.add_argument("--overview-digest", action="store_true", help="Action: shows a short digest of the portfolio status. Also, you can define `--output` key to save this information to file, default: `overview-digest.md`.")
4789    parser.add_argument("--overview-positions", action="store_true", help="Action: shows only open positions. Also, you can define `--output` key to save this information to file, default: `overview-positions.md`.")
4790    parser.add_argument("--overview-orders", action="store_true", help="Action: shows only sections of open limits and stop orders. Also, you can define `--output` key to save orders to file, default: `overview-orders.md`.")
4791    parser.add_argument("--overview-analytics", action="store_true", help="Action: shows only the analytics section and the distribution of the portfolio by various categories. Also, you can define `--output` key to save this information to file, default: `overview-analytics.md`.")
4792    parser.add_argument("--overview-calendar", action="store_true", help="Action: shows only the bonds calendar section (if these present in portfolio). Also, you can define `--output` key to save this information to file, default: `overview-calendar.md`.")
4793
4794    parser.add_argument("--deals", "-d", type=str, nargs="*", help="Action: show all deals between two given dates. Start day may be an integer number: -1, -2, -3 days ago. Also, you can use keywords: `today`, `yesterday` (-1), `week` (-7), `month` (-30) and `year` (-365). Dates format must be: `%%Y-%%m-%%d`, e.g. 2020-02-03. With `--no-cancelled` key information about cancelled operations will be removed from the deals report. Also, you can define `--output` key to save all deals to file, default: `deals.md`.")
4795    parser.add_argument("--history", type=str, nargs="*", help="Action: get last history candles of the current instrument defined by `--ticker` or `--figi` (FIGI id) keys. History returned between two given dates: `start` and `end`. Minimum requested date in the past is `1970-01-01`. This action may be used together with the `--render-chart` key. Also, you can define `--output` key to save history candlesticks to file.")
4796    parser.add_argument("--load-history", type=str, help="Action: try to load history candles from given csv-file as a Pandas Dataframe and print it in to the console. This action may be used together with the `--render-chart` key.")
4797    parser.add_argument("--render-chart", type=str, help="Action: render candlesticks chart. This key may only used with `--history` or `--load-history` together. Action has 1 parameter with two possible string values: `interact` (`i`) or `non-interact` (`ni`).")
4798
4799    parser.add_argument("--trade", nargs="*", help="Action: universal action to open market position for defined ticker or FIGI. You must specify 1-5 parameters: [direction `Buy` or `Sell`] [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. See examples in readme.")
4800    parser.add_argument("--buy", nargs="*", help="Action: immediately open BUY market position at the current price for defined ticker or FIGI. You must specify 0-4 parameters: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`].")
4801    parser.add_argument("--sell", nargs="*", help="Action: immediately open SELL market position at the current price for defined ticker or FIGI. You must specify 0-4 parameters: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`].")
4802
4803    parser.add_argument("--order", nargs="*", help="Action: universal action to open limit or stop-order in any directions. You must specify 4-7 parameters: [direction `Buy` or `Sell`] [order type `Limit` or `Stop`] [lots] [target price] [maybe for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]]. See examples in readme.")
4804    parser.add_argument("--buy-limit", type=float, nargs=2, help="Action: open pending BUY limit-order (below current price). You must specify only 2 parameters: [lots] [target price] to open BUY limit-order. If you try to create `Buy` limit-order above current price then broker immediately open `Buy` market order, such as if you do simple `--buy` operation!")
4805    parser.add_argument("--sell-limit", type=float, nargs=2, help="Action: open pending SELL limit-order (above current price). You must specify only 2 parameters: [lots] [target price] to open SELL limit-order. If you try to create `Sell` limit-order below current price then broker immediately open `Sell` market order, such as if you do simple `--sell` operation!")
4806    parser.add_argument("--buy-stop", nargs="*", help="Action: open BUY stop-order. You must specify at least 2 parameters: [lots] [target price] to open BUY stop-order. In additional you can specify 3 parameters for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. When current price will go up or down to target price value then broker opens a limit order. Stop loss order always executed by market price.")
4807    parser.add_argument("--sell-stop", nargs="*", help="Action: open SELL stop-order. You must specify at least 2 parameters: [lots] [target price] to open SELL stop-order. In additional you can specify 3 parameters for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. When current price will go up or down to target price value then broker opens a limit order. Stop loss order always executed by market price.")
4808    # parser.add_argument("--buy-limit-order-grid", type=str, nargs="*", help="Action: open grid of pending BUY limit-orders (below current price). Parameters format: l(ots)=[L_int,...] p(rices)=[P_float,...]. Counts of values in lots and prices lists must be equals!")
4809    # parser.add_argument("--sell-limit-order-grid", type=str, nargs="*", help="Action: open grid of pending SELL limit-orders (above current price). Parameters format: l(ots)=[L_int,...] p(rices)=[P_float,...]. Counts of values in lots and prices lists must be equals!")
4810
4811    parser.add_argument("--close-order", "--cancel-order", type=str, nargs=1, help="Action: close only one order by it's `orderId` or `stopOrderId`. You can find out the meaning of these IDs using the key `--overview`.")
4812    parser.add_argument("--close-orders", "--cancel-orders", type=str, nargs="+", help="Action: close one or list of orders by it's `orderId` or `stopOrderId`. You can find out the meaning of these IDs using the key `--overview`.")
4813    parser.add_argument("--close-trade", "--cancel-trade", action="store_true", help="Action: close only one position for instrument defined by `--ticker` (high priority) or `--figi` keys, including for currencies tickers.")
4814    parser.add_argument("--close-trades", "--cancel-trades", type=str, nargs="+", help="Action: close positions for list of tickers or FIGIs, including for currencies tickers or FIGIs.")
4815    parser.add_argument("--close-all", "--cancel-all", type=str, nargs="*", help="Action: close all available (not blocked) opened trades and orders, excluding for currencies. Also you can select one or more keywords case insensitive to specify trades type: `orders`, `shares`, `bonds`, `etfs` and `futures`, but not `currencies`. Currency positions you must closes manually using `--buy`, `--sell`, `--close-trade` or `--close-trades` operations. If the `--close-all` key present with the `--ticker` or `--figi` keys, then positions and all open limit and stop orders for the specified instrument are closed.")
4816
4817    parser.add_argument("--limits", "--withdrawal-limits", "-w", action="store_true", help="Action: show table of funds available for withdrawal for current `accountId`. You can change `accountId` with the key `--account-id`. Also, you can define `--output` key to save this information to file, default: `limits.md`.")
4818    parser.add_argument("--user-info", "-u", action="store_true", help="Action: show all available user's data (`accountId`s, common user information, margin status and tariff connections limit). Also, you can define `--output` key to save this information to file, default: `user-info.md`.")
4819    parser.add_argument("--account", "--accounts", "-a", action="store_true", help="Action: show simple table with all available user accounts. Also, you can define `--output` key to save this information to file, default: `accounts.md`.")
4820
4821    cmdArgs = parser.parse_args()
4822    return cmdArgs
4823
4824
4825def Main(**kwargs):
4826    """
4827    Main function for work with TKSBrokerAPI in the console.
4828
4829    See examples:
4830    - in english: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md
4831    - in russian: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README.md
4832    """
4833    args = Args(**kwargs) if kwargs else ParseArgs()  # get and parse command-line parameters or use **kwarg parameters
4834
4835    if args.debug_level:
4836        uLogger.level = 10  # always debug level by default
4837        uLogger.handlers[0].level = args.debug_level  # level for STDOUT
4838
4839    exitCode = 0
4840    start = datetime.now(tzutc())
4841    uLogger.debug("=-" * 50)
4842    uLogger.debug(">>> TKSBrokerAPI module started at: [{}] UTC, it is [{}] local time".format(
4843        start.strftime(TKS_PRINT_DATE_TIME_FORMAT),
4844        start.astimezone(tzlocal()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
4845    ))
4846
4847    # trying to calculate full current version:
4848    buildVersion = __version__
4849    try:
4850        v = version("tksbrokerapi")
4851        buildVersion = v if v.startswith(buildVersion) else buildVersion + ".dev0"  # set version as major.minor.dev0 if run as local build or local script
4852
4853    except Exception:
4854        buildVersion = __version__ + ".dev0"  # if an errors occurred then also set version as major.minor.dev0
4855
4856    uLogger.debug("TKSBrokerAPI major.minor.build version used: [{}]".format(buildVersion))
4857    uLogger.debug("Host CPU count: [{}]".format(CPU_COUNT))
4858
4859    try:
4860        if args.version:
4861            print("TKSBrokerAPI {}".format(buildVersion))
4862            uLogger.debug("User requested current TKSBrokerAPI major.minor.build version: [{}]".format(buildVersion))
4863
4864        else:
4865            # Init class for trading with Tinkoff Broker:
4866            trader = TinkoffBrokerServer(
4867                token=args.token,
4868                accountId=args.account_id,
4869                useCache=not args.no_cache,
4870            )
4871
4872            # --- set some options:
4873
4874            if args.more:
4875                trader.moreDebug = True
4876                uLogger.warning("More debug info mode is enabled! See network requests, responses and its headers in the full log or run TKSBrokerAPI platform with the `--verbosity 10` to show theres in console.")
4877
4878            if args.html:
4879                trader.useHTMLReports = True
4880
4881            if args.ticker:
4882                ticker = str(args.ticker).upper()  # Tickers may be upper case only
4883
4884                if ticker in trader.aliasesKeys:
4885                    trader.ticker = trader.aliases[ticker]  # Replace some tickers with its aliases
4886
4887                else:
4888                    trader.ticker = ticker
4889
4890            if args.figi:
4891                trader.figi = str(args.figi).upper()  # FIGIs may be upper case only
4892
4893            if args.depth is not None:
4894                trader.depth = args.depth
4895
4896            # --- do one command:
4897
4898            if args.list:
4899                if args.output is not None:
4900                    trader.instrumentsFile = args.output
4901
4902                trader.ShowInstrumentsInfo(show=True)
4903
4904            elif args.list_xlsx:
4905                trader.DumpInstrumentsAsXLSX(forceUpdate=False)
4906
4907            elif args.bonds_xlsx is not None:
4908                if args.output is not None:
4909                    trader.bondsXLSXFile = args.output
4910
4911                if len(args.bonds_xlsx) == 0:
4912                    trader.ExtendBondsData(instruments=trader.iList["Bonds"].keys(), xlsx=True)  # request bonds with all available tickers
4913
4914                else:
4915                    trader.ExtendBondsData(instruments=args.bonds_xlsx, xlsx=True)  # request list of given bonds
4916
4917            elif args.search:
4918                if args.output is not None:
4919                    trader.searchResultsFile = args.output
4920
4921                trader.SearchInstruments(pattern=args.search[0], show=True)
4922
4923            elif args.info:
4924                if not (args.ticker or args.figi):
4925                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
4926                    raise Exception("Ticker or FIGI required")
4927
4928                if args.output is not None:
4929                    trader.infoFile = args.output
4930
4931                if args.ticker:
4932                    trader.SearchByTicker(requestPrice=True, show=True)  # show info and current prices by ticker name
4933
4934                else:
4935                    trader.SearchByFIGI(requestPrice=True, show=True)  # show info and current prices by FIGI id
4936
4937            elif args.calendar is not None:
4938                if args.output is not None:
4939                    trader.calendarFile = args.output
4940
4941                if len(args.calendar) == 0:
4942                    bondsData = trader.ExtendBondsData(instruments=trader.iList["Bonds"].keys(), xlsx=False)  # request bonds with all available tickers
4943
4944                else:
4945                    bondsData = trader.ExtendBondsData(instruments=args.calendar, xlsx=False)  # request list of given bonds
4946
4947                trader.ShowBondsCalendar(extBonds=bondsData, show=True)  # shows bonds payment calendar only
4948
4949            elif args.price:
4950                if not (args.ticker or args.figi):
4951                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
4952                    raise Exception("Ticker or FIGI required")
4953
4954                trader.GetCurrentPrices(show=True)
4955
4956            elif args.prices is not None:
4957                if args.output is not None:
4958                    trader.pricesFile = args.output
4959
4960                trader.GetListOfPrices(instruments=args.prices, show=True)  # WARNING: too long wait for a lot of instruments prices
4961
4962            elif args.overview:
4963                if args.output is not None:
4964                    trader.overviewFile = args.output
4965
4966                trader.Overview(show=True, details="full")
4967
4968            elif args.overview_digest:
4969                if args.output is not None:
4970                    trader.overviewDigestFile = args.output
4971
4972                trader.Overview(show=True, details="digest")
4973
4974            elif args.overview_positions:
4975                if args.output is not None:
4976                    trader.overviewPositionsFile = args.output
4977
4978                trader.Overview(show=True, details="positions")
4979
4980            elif args.overview_orders:
4981                if args.output is not None:
4982                    trader.overviewOrdersFile = args.output
4983
4984                trader.Overview(show=True, details="orders")
4985
4986            elif args.overview_analytics:
4987                if args.output is not None:
4988                    trader.overviewAnalyticsFile = args.output
4989
4990                trader.Overview(show=True, details="analytics")
4991
4992            elif args.overview_calendar:
4993                if args.output is not None:
4994                    trader.overviewAnalyticsFile = args.output
4995
4996                trader.Overview(show=True, details="calendar")
4997
4998            elif args.deals is not None:
4999                if args.output is not None:
5000                    trader.reportFile = args.output
5001
5002                if 0 <= len(args.deals) < 3:
5003                    trader.Deals(
5004                        start=args.deals[0] if len(args.deals) >= 1 else None,
5005                        end=args.deals[1] if len(args.deals) == 2 else None,
5006                        show=True,  # Always show deals report in console
5007                        showCancelled=not args.no_cancelled,  # If --no-cancelled key then remove cancelled operations from the deals report. False by default.
5008                    )
5009
5010                else:
5011                    uLogger.error("You must specify 0-2 parameters: [DATE_START] [DATE_END]")
5012                    raise Exception("Incorrect value")
5013
5014            elif args.history is not None:
5015                if args.output is not None:
5016                    trader.historyFile = args.output
5017
5018                if 0 <= len(args.history) < 3:
5019                    dataReceived = trader.History(
5020                        start=args.history[0] if len(args.history) >= 1 else None,
5021                        end=args.history[1] if len(args.history) == 2 else None,
5022                        interval="hour" if args.interval is None or not args.interval else args.interval,
5023                        onlyMissing=False if args.only_missing is None or not args.only_missing else args.only_missing,
5024                        csvSep="," if args.csv_sep is None or not args.csv_sep else args.csv_sep,
5025                        show=True,  # shows all downloaded candles in console
5026                    )
5027
5028                    if args.render_chart is not None and dataReceived is not None:
5029                        iChart = False if args.render_chart.lower() == "ni" or args.render_chart.lower() == "non-interact" else True
5030
5031                        trader.ShowHistoryChart(
5032                            candles=dataReceived,
5033                            interact=iChart,
5034                            openInBrowser=False,  # False by default, to avoid issues with `permissions denied` to html-file.
5035                        )
5036
5037                else:
5038                    uLogger.error("You must specify 0-2 parameters: [DATE_START] [DATE_END]")
5039                    raise Exception("Incorrect value")
5040
5041            elif args.load_history is not None:
5042                histData = trader.LoadHistory(filePath=args.load_history)  # load data from file and show history in console
5043
5044                if args.render_chart is not None and histData is not None:
5045                    iChart = False if args.render_chart.lower() == "ni" or args.render_chart.lower() == "non-interact" else True
5046                    trader.ticker = os.path.basename(args.load_history)  # use filename as ticker name for PriceGenerator's chart
5047
5048                    trader.ShowHistoryChart(
5049                        candles=histData,
5050                        interact=iChart,
5051                        openInBrowser=False,  # False by default, to avoid issues with `permissions denied` to html-file.
5052                    )
5053
5054            elif args.trade is not None:
5055                if 1 <= len(args.trade) <= 5:
5056                    trader.Trade(
5057                        operation=args.trade[0],
5058                        lots=int(args.trade[1]) if len(args.trade) >= 2 else 1,
5059                        tp=float(args.trade[2]) if len(args.trade) >= 3 else 0.,
5060                        sl=float(args.trade[3]) if len(args.trade) >= 4 else 0.,
5061                        expDate=args.trade[4] if len(args.trade) == 5 else "Undefined",
5062                    )
5063
5064                else:
5065                    uLogger.error("You must specify 1-5 parameters to open trade: [direction `Buy` or `Sell`] [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
5066
5067            elif args.buy is not None:
5068                if 0 <= len(args.buy) <= 4:
5069                    trader.Buy(
5070                        lots=int(args.buy[0]) if len(args.buy) >= 1 else 1,
5071                        tp=float(args.buy[1]) if len(args.buy) >= 2 else 0.,
5072                        sl=float(args.buy[2]) if len(args.buy) >= 3 else 0.,
5073                        expDate=args.buy[3] if len(args.buy) == 4 else "Undefined",
5074                    )
5075
5076                else:
5077                    uLogger.error("You must specify 0-4 parameters to open buy position: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
5078
5079            elif args.sell is not None:
5080                if 0 <= len(args.sell) <= 4:
5081                    trader.Sell(
5082                        lots=int(args.sell[0]) if len(args.sell) >= 1 else 1,
5083                        tp=float(args.sell[1]) if len(args.sell) >= 2 else 0.,
5084                        sl=float(args.sell[2]) if len(args.sell) >= 3 else 0.,
5085                        expDate=args.sell[3] if len(args.sell) == 4 else "Undefined",
5086                    )
5087
5088                else:
5089                    uLogger.error("You must specify 0-4 parameters to open sell position: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
5090
5091            elif args.order:
5092                if 4 <= len(args.order) <= 7:
5093                    trader.Order(
5094                        operation=args.order[0],
5095                        orderType=args.order[1],
5096                        lots=int(args.order[2]),
5097                        targetPrice=float(args.order[3]),
5098                        limitPrice=float(args.order[4]) if len(args.order) >= 5 else 0.,
5099                        stopType=args.order[5] if len(args.order) >= 6 else "Limit",
5100                        expDate=args.order[6] if len(args.order) == 7 else "Undefined",
5101                    )
5102
5103                else:
5104                    uLogger.error("You must specify 4-7 parameters to open order: [direction `Buy` or `Sell`] [order type `Limit` or `Stop`] [lots] [target price] [maybe for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]]. See: `python TKSBrokerAPI.py --help`")
5105
5106            elif args.buy_limit:
5107                trader.BuyLimit(lots=int(args.buy_limit[0]), targetPrice=args.buy_limit[1])
5108
5109            elif args.sell_limit:
5110                trader.SellLimit(lots=int(args.sell_limit[0]), targetPrice=args.sell_limit[1])
5111
5112            elif args.buy_stop:
5113                if 2 <= len(args.buy_stop) <= 7:
5114                    trader.BuyStop(
5115                        lots=int(args.buy_stop[0]),
5116                        targetPrice=float(args.buy_stop[1]),
5117                        limitPrice=float(args.buy_stop[2]) if len(args.buy_stop) >= 3 else 0.,
5118                        stopType=args.buy_stop[3] if len(args.buy_stop) >= 4 else "Limit",
5119                        expDate=args.buy_stop[4] if len(args.buy_stop) == 5 else "Undefined",
5120                    )
5121
5122                else:
5123                    uLogger.error("You must specify 2-5 parameters for buy stop-order: [lots] [target price] [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
5124
5125            elif args.sell_stop:
5126                if 2 <= len(args.sell_stop) <= 7:
5127                    trader.SellStop(
5128                        lots=int(args.sell_stop[0]),
5129                        targetPrice=float(args.sell_stop[1]),
5130                        limitPrice=float(args.sell_stop[2]) if len(args.sell_stop) >= 3 else 0.,
5131                        stopType=args.sell_stop[3] if len(args.sell_stop) >= 4 else "Limit",
5132                        expDate=args.sell_stop[4] if len(args.sell_stop) == 5 else "Undefined",
5133                    )
5134
5135                else:
5136                    uLogger.error("You must specify 2-5 parameters for sell stop-order: [lots] [target price] [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]. See: python TKSBrokerAPI.py --help")
5137
5138            # elif args.buy_order_grid is not None:
5139            #     # update order grid work with api v2
5140            #     if len(args.buy_order_grid) == 2:
5141            #         orderParams = trader.ParseOrderParameters(operation="Buy", **dict(kw.split('=') for kw in args.buy_order_grid))
5142            #
5143            #         for order in orderParams:
5144            #             trader.Order(operation="Buy", lots=order["lot"], price=order["price"])
5145            #
5146            #     else:
5147            #         uLogger.error("To open grid of pending BUY limit-orders (below current price) you must specified 2 parameters: l(ots)=[L_int,...] p(rices)=[P_float,...]. See: `python TKSBrokerAPI.py --help`")
5148            #
5149            # elif args.sell_order_grid is not None:
5150            #     # update order grid work with api v2
5151            #     if len(args.sell_order_grid) >= 2:
5152            #         orderParams = trader.ParseOrderParameters(operation="Sell", **dict(kw.split('=') for kw in args.sell_order_grid))
5153            #
5154            #         for order in orderParams:
5155            #             trader.Order(operation="Sell", lots=order["lot"], price=order["price"])
5156            #
5157            #     else:
5158            #         uLogger.error("To open grid of pending SELL limit-orders (above current price) you must specified 2 parameters: l(ots)=[L_int,...] p(rices)=[P_float,...]. See: `python TKSBrokerAPI.py --help`")
5159
5160            elif args.close_order is not None:
5161                trader.CloseOrders(args.close_order)  # close only one order
5162
5163            elif args.close_orders is not None:
5164                trader.CloseOrders(args.close_orders)  # close list of orders
5165
5166            elif args.close_trade:
5167                if not (args.ticker or args.figi):
5168                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
5169                    raise Exception("Ticker or FIGI required")
5170
5171                if args.ticker:
5172                    trader.CloseTrades([str(args.ticker).upper()])  # close only one trade by ticker (priority)
5173
5174                else:
5175                    trader.CloseTrades([str(args.figi).upper()])  # close only one trade by FIGI
5176
5177            elif args.close_trades is not None:
5178                trader.CloseTrades(args.close_trades)  # close trades for list of tickers
5179
5180            elif args.close_all is not None:
5181                if args.ticker:
5182                    trader.CloseAllByTicker(instrument=str(args.ticker).upper())
5183
5184                elif args.figi:
5185                    trader.CloseAllByFIGI(instrument=str(args.figi).upper())
5186
5187                else:
5188                    trader.CloseAll(*args.close_all)
5189
5190            elif args.limits:
5191                if args.output is not None:
5192                    trader.withdrawalLimitsFile = args.output
5193
5194                trader.OverviewLimits(show=True)
5195
5196            elif args.user_info:
5197                if args.output is not None:
5198                    trader.userInfoFile = args.output
5199
5200                trader.OverviewUserInfo(show=True)
5201
5202            elif args.account:
5203                if args.output is not None:
5204                    trader.userAccountsFile = args.output
5205
5206                trader.OverviewAccounts(show=True)
5207
5208            else:
5209                uLogger.error("There is no command to execute! One of the possible commands must be selected. See help with `--help` key.")
5210                raise Exception("There is no command to execute")
5211
5212    except Exception:
5213        trace = tb.format_exc()
5214        for e in ["socket.gaierror", "nodename nor servname provided", "or not known", "NewConnectionError", "[Errno 8]", "Failed to establish a new connection"]:
5215            if e in trace:
5216                uLogger.error("Check your Internet connection! Failed to establish connection to broker server!")
5217                break
5218
5219        uLogger.debug(trace)
5220        uLogger.debug("Please, check issues or request a new one at https://github.com/Tim55667757/TKSBrokerAPI/issues")
5221        exitCode = 255  # an error occurred, must be open a ticket for this issue
5222
5223    finally:
5224        finish = datetime.now(tzutc())
5225
5226        if exitCode == 0:
5227            if args.more:
5228                uLogger.debug("All operations were finished success (summary code is 0).")
5229
5230        else:
5231            uLogger.error("An issue occurred with TKSBrokerAPI module! See full debug log in [{}] or run TKSBrokerAPI once again with the key `--debug-level 10`. Summary code: {}".format(
5232                os.path.abspath(uLog.defaultLogFile), exitCode,
5233            ))
5234
5235        uLogger.debug(">>> TKSBrokerAPI module work duration: [{}]".format(finish - start))
5236        uLogger.debug(">>> TKSBrokerAPI module finished: [{} UTC], it is [{}] local time".format(
5237            finish.strftime(TKS_PRINT_DATE_TIME_FORMAT),
5238            finish.astimezone(tzlocal()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
5239        ))
5240        uLogger.debug("=-" * 50)
5241
5242        if not kwargs:
5243            sys.exit(exitCode)
5244
5245        else:
5246            return exitCode
5247
5248
5249if __name__ == "__main__":
5250    Main()